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ABOUT THIS PUBLICATION 


VS APL is a program product that interprets and executes statements written 
in APL (A Programming Language). This publication describes how to install 
VS APL and how to perform various system management functions such as 
converting workspaces, defining VS APL users, and maintaining public and 
project libraries. It is intended for those who have responsibility for these 
functions. The reader is assumed to have knowledge of VS APL and 
Conversational Monitor System (CMS), which runs under VM/370, or VS 
Personal Computing (VSPC), which runs under OS/VS1 (Program Number 
5740-XR5), OS/VS2 MVS (Program Number 5740-XR6), or DOS/VS 
(Program Number 5746-XR3). (For the remainder of the publication, the 
term OS/VS2 will be used to represent OS/VS2 MVS.) 


Major Divisions of the Publication 
“Introduction” describes the components of VS APL. 


“VS APL Distribution Volume” describes the contents and format of the VS 
APL distribution volume. 


“Installing VS APL under VM/370 (CMS)” explains how to install VS APL 
as a Shared or non-shared system under VM/370 (CMS). 


“Installing VS APL under OS/VS (VSPC)” explains how to install VS APL 
as a foreground processor under OS/VS (VSPC). 


“Installing VS APL under DOS/VS (VSPC)” explains how to install VS APL 
as a foreground processor under DOS/VS (VSPC). 


‘Defining VS APL Users” explains how to define VS APL users to the host 
system. 


“Defining Auxiliary Processors’’ explains how to define auxiliary processors 
to the host system. 


“VS APL Public and Project Libraries” explains how to create and maintain 
VS APL public and project libraries. 


‘‘Workspace Conversion” explains how to convert APL\360, APLSV, and 
APL/CMS workspaces to VS APL workspaces for use under CMS or VSPC. 


“Transporting Workspaces between CMS and VSPC”’ explains how to 
transport VS APL workspaces between CMS and VSPC. 


“Using the VS APL Microcode Assist” discusses the use of the VS AP 
microcode assist feature. ~ 


“Storage Requirements” presents virtual storage and auxiliary storage 
requirements for VS APL. : 


““Messages”’ contains information about error and diagnostic messages. 


“Appendix A. VS APL Components”’ lists the items contained in each 
component of VS APL. . 


“Appendix B. Sample Terminal Session for VS APL under CMS” contains a 
sample terminal session that can be used to test that VS APL is installed 
correctly under CMS. 
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“Appendix C. Sample Terminal Session for VS APL under VSPC”’ contains a 
sample terminal session that can be used to test that VS APL is installed 
correctly under OS/VS (VSPC) or DOS/VS (VSPC). 


Conventions Used in the Publication 


The conventions used in describing the syntax of commands and statements 
are: 


Required Publications 


Expressions enclosed in brackets, [], are optional. 


Items separated by an OR sign, |, are alternatives, only one of which may 
be specified. 


Uppercase items must be entered as shown except that they may be 
truncated if so noted and, if entered at a terminal, they may be entered as 
either lowercase or uppercase. 


Lowercase items are variables for which a value is substituted. 


Parentheses, (), must be entered as shown. 


All readers must be familiar with some of the information presented in this 
publication: 


VS APL General Information, GH20-9064, which provides a general 
description of VS APL. 


Readers concerned with VS APL under CMS must be familiar with some of 
the information presented in these publications: 


IBM Virtual Machine Facility/370: Introduction, GC20-1800, which 
provides a general description of VM/370 and CMS. 


IBM Virtual Machine Facility/370: Command Language Guide for 
General Users, GC20-1804, which provides basic information about CMS 
and CP for VM/370 Release 2. 


IBM Virtual Machine Facility/370: Operator’s Guide, GC20-1806, 
which describes how to define VM/370 users and CMS virtual disks. 


IBM Virtual Machine Facility/370: EDIT Guide, GC20-1805, which 
describes how to use the CMS editor for VM/370 Release 2. 


VS APL for CMS: Terminal User’s Guide, SH20-9067, which 
describes how to use VS APL under CMS. 


IBM Virtual Machine Facility/370: CMS User’s Guide, GC20-1819, 
which provides basic information about CMS and how to use the CMS 
editor to create and modify programs for VM/370 Release 3. 


IBM Virtual Machine Facility/370: CP Command Reference for 
General Users, GC20-1820, which provides basic information about CP 
for VM/370 Release 3. 


IBM Virtual Machine Facility/370: Command and Macro Reference, 
GC20-1818, which provides reference material on CMS commands, 
subcommands, and macros for VM/370 Release 3. 
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Related Publications 


Readers concerned with VS APL under VSPC must be familiar with some of 
the information presented in these publications: 


e VS Personal Computing (VSPC) for OS/VS and DOS/VS: General 
Information, GH20-9070, which provides a general description of VSPC. 


e VS Personal Computing (VSPC) Installation Reference Material, 
SH20-9072, which describes the VSPC Service Program and VSPC 
commands. This publication also contains information on OS/VS and 
DOS/VS (VSPC) messages. 


e. VS APL for VSPC: Terminal User’s Guide, SH20-9066, which 
describes how to use VS APL under VSPC. 


Readers concerned with VS APL under OS/VS (VSPC) must be familiar 
with some of the information presented in this publication: 


« OS/VS JCL Reference, GC28-0618, which describes the OS/VS JCL 
statements used in this publication. 


Readers concerned with VS APL under DOS/VS (VSPC) must be familiar 
with some of the information presented in this publication: 


« DOS/VS System Control Statements, GC33-5376, which describes the 
DOS/VS control statements used in this publication. 


Readers may need to be familiar with some of the information presented in 
these publications: 


¢ Operator’s Library: System/370 Model 135 Procedures, GC38-0005, 
which explains how to load the VS APL microcode assist feature on a 
System/370, Model 135. 


e IBM System/370 Model 145 Operating Procedures, GC38-0015, which 
explains how to load the VS APL microcode assist feature on a 
System/370, Model 145. 


e IBM Virtual Machine Facility/370: System Messages, GC20-1808, 
which lists CP and CMS messages. 


« DOS/VS Messages, GC33-5379, which lists DOS/VS (VSPC) messages. 


e IBM Virtual Machine Facility/370: System Programmer’s Guide, 
GC20-1807, which describes shared systems. 


e IBM Virtual Machine Facility/370: Planning and System Generation 
Guide, GC20-1801, which describes how to implement a shared system. 
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SUMMARY OF AMENDMENTS 


Release 2, October, 1976 


New Auxiliary Processors and Distributed Workspaces 
New Programming Features 
VS APL is distributed with the following additional items: 
Item Description 


Full Screen Management An auxiliary processor (number 124) that can 
auxiliary processor be used with VS APL under VSPC. 


CMS VSAM An auxiliary processor (number 123) that can 
auxiliary processor be used with VS APL under CMS. 

MEDIT A public library 1 workspace. 

SEDIT A public library 1 workspace. 

HOWEDITS A public library 1 workspace. 

SBIC A public library 1 workspace. 

VSAPLFILE A public library 2 workspace (VS APL under 
VSPC). 

FULLSCREEN A public library 2 workspace (VS APL under 
VSPC). 

PRINT A public library 2 workspace (VS APL under 
CMS). 


Information pertinent to these new items has been added to the Introduction, 
to the sample terminal session for VS APL under CMS, and to the 
descriptions of the VS APL distribution volume, VS APL installation 
procedures for CMS and VSPC, and auxiliary processors. 


DOS/VS Conversion Program 
New Programming Feature 


VS APL now includes a workspace conversion program (APLCVDOS) that 
executes under DOS/VS(VSPC). A description of the procedure for 
executing the DOS/VS conversion program is now provided in the chapter 
“Workspace Conversion.” 


DOS/VS Installation Information 
Service Changes 


A new chapter, describing how to install VS APL under DOS/VS (VSPC), 
has been added to the text. Virtual and auxiliary storage requirements for VS 
APL under DOS/VS (VSPC) have been added to the chapter “Storage 
Requirements.” 
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Transporting Workspaces 
Service Change 


Various changes have been made to the procedures shown for VS APL 
workspace transport from CMS to VSPC and from VSPC to CMS. 
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INTRODUCTION 


VS APL is a program product that interprets and executes statements written 
in APL (A Programming Language). It runs under: 


¢ Conversational Monitor System (CMS), which runs under VM/370 


¢ VS Personal Computing (VSPC), which runs under OS/VS1, OS/VS2, 
and DOS/VS 


VS APL is divided into the six components described below. 


Interpreter: Scans, analyzes, and executes VS APL statements. It is fully 
independent of the environment in which VS APL operates. It is free of all 
dependencies on terminal type, library organization, host system, and other 
characteristics of a particular installation. 


Executor: Provides environment-dependent services for the interpreter, such 
as access to libraries and terminal input and output. There are two versions of 
the executor, one for use under CMS and one for use under VSPC. 


Shared Storage Manager: Enables programs that are operating concurrently 
to communicate with each other via shared variables. The shared storage 
manager distributed with VS APL is used only under CMS. Under VSPC, the 
shared storage manager is a component of VSPC. 


Auxiliary Processors: Provide services to VS APL users via shared variables. 
There are four internal auxiliary processors for use under VSPC; they are 
distributed as part of the executor. There are five auxiliary processors for use 
under CMS; they are distributed as a separate component. Also distributed 
with VS APL, for use under CMS only, is a set of macros that can be used to 
write auxiliary processors. Distributed with VSPC is a set of similar macros 
that comprise the VSPC background interface. 


Conversion Program: Converts APL\360, APLSV, and APL/CMS 
workspaces to VS APL workspaces. There are four versions of the conversion 
program, two for use under CMS, one for use under OS/VS, and one for use 
under DOS/VS. . | 


Distributed Workspaces: Provide useful functions for VS APL users. They are 
described in VS APL for CMS: Terminal User’s Guide and VS APL for 
VSPC: Terminal User’s Guide. 
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VS APL DISTRIBUTION VOLUME 


The VS APL distribution volume contains all the components of VS APL and 
the sample job control statements and procedures used to install it. For 
installation under VM/370 (CMS) and OS/VS (VSPC), the distribution 
volume is an unlabeled tape. For installation under DOS/VS (VSPC), the 
distribution volume is either an unlabeled tape or a disk. The format of the 
distribution tape volume is shown in Figure 1. The format of the distribution 
disk volume is shown in Figure 2. 
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File File Characteristics 
Number Contents RECFM LRECL BLKSIZE 


1 All object code for DOS/VS (VSPC); FB 80 3440 
interpreter, executor (including internal 
auxiliary processors), and conversion 
| program. 


Zz Sample job control statements to install F 80 80 
under DOS/VS and to run the conversion 
| . program. 


3 ‘ Sample job control statements to install F 80 80 
under OS/VS and to run the conversion 
program. 


4 EXEC procedure to install under CMS; F 805 805 
in CMS TAPE DUMP format. 


/ 5 Object code for the interpreter for CMS FB 80 3200 
and OS/VS (VSPC). 


6 Object code and other data for CMS; F 805 805 
executor, shared storage manager, 
auxiliary processors and auxiliary 
processor macros, conversion programs, 
and conversion procedures; in CMS TAPE 
DUMP format. 


7 Object code for OS/VS (VSPC); executor FB 80 3200 
(including internal auxiliary processors), 
and conversion program. 


8 Workspace 1 NEWS F 800 800 

9 Workspace 1 WSFNS F 800 800° 
10 Workspace 1 CONVERT F 800 800 
11 Workspace | TYPEDRILL F 800 | 800 
12 Workspace 1 APLCOURSE F 800 800 
13 Workspace 1 PLOT F 800 800 
14 Workspace 1 EXAMPLES F 800 800 
15 Workspace 1 FORMAT F 800 800 
16 Workspace 1 MEDIT F 800 800 
17 Workspace 1 SEDIT F 800 800 
18 Workspace 1 HOWEDITS F 800 800 
19 Workspace 1 SBIC F 800 800 
20 Workspace 2 VSFILES! F 800 800 
21 Workspace 2 VSAPLFILE! F 800 800 
22 Workspace 2 FULLSCREEN! F 800 800 
23 Workspace 2 APFNS2 F 800 800 
24 Workspace 2 PRINT2 F 800 800 


1 Workspace is used only under VSPC, 
2 Workspace is used only under CMS. 


Figure 1. Format of VS APL Distribution Tape Volume 
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Data Set Name 
A5748AP1.DOSVSOBJ.VSAPL 


A5748AP1.DOSVSJCL.VSAPL 


AS748AP1.NEWS.VSAPL 
A5748AP1.WSENS.VSAPL 
A5748AP1.CONVERT.VSAPL 
A5748AP1.TYPEDRIL.VSAPL 
A5748AP1.APLCOURS.VSAPL 
AS748AP1.PLOT.VSAPL _ 
A5748AP1.EXAMPLES.VSAPL 
AS748AP1.FORMAT.VSAPL 
A5748AP1.MEDIT.VSAPL 
A5748AP1.SEDIT.VSAPL 
A5748AP1.HOWEDITS.VSAPL 
A5S748AP1.SBIC.VSAPL 
A5748AP1.VSFILES.VSAPL 
A5748AP1.VSAPLFIL.VSAPL 
A5748AP1.FULLSCRE.VSAPL 


Contents 


All object code for DOS/VS (VSPC); 
interpreter, executor (including 
internal auxiliary processors), 

and conversion program. 


Sample job control statements to 
install under DOS/VS and to run 
the conversion program. 


Workspace 1 NEWS 
Workspace | WSFNS 
Workspace 1 CONVERT 
Workspace | TYPEDRILL 
Workspace |. APLCOURSE 
Workspace 1 PLOT 
Workspace 1 EXAMPLES 
Workspace | FORMAT 
Workspace 1 MEDIT 
Workspace 1 SEDIT 
Workspace | HOWEDITS 
Workspace | SBIC 
Workspace 2 VSFILES 
Workspace 2 VSAPLFILE 
Workspace 2 FULLSCREEN 


Figure 2. Format of VS APL Distribution Disk Volume 


File Characteristics 


RECFM LRECL BLKSIZE 
FB 80 3440 
F 80 80 
FB 80 ~ 800 
FB 80 800 
FB 80 800 
FB 80 800 
FB 80 800 
FB 80 800 
FB 80 800 
FB 80 800 
FB 80 800 
FB 80 800 
FB 80 800 
FB 80 800 
FB 80 800 
FB 80 800 
FB 80 800 
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INSTALLING VS APL UNDER VM/370 (CMS) 


This section describes how to install VS APL as a shared or non-shared 
system under VM/370 (CMS). Installing VS APL as a shared system makes 
more efficient use of real storage and improves system performance. When 
VS APL is a shared system, all users share one copy of the VS APL executor, 
interpreter, and shared storage manager; an initialization routine and translate 
tables (executor modules APLSCINI and APLSCTBL) reside in each user’s 
virtual machine. When VS APL is a non-shared system, the VS APL 
executor, interpreter, and shared storage manager reside in each user’s virtual 
machine. Whether VS APL is shared or not, any auxiliary processors invoked 
by a user reside in his virtual machine. 


Before installing VS APL as a shared system, you should be familiar with the 
information about saved systems and shared segments presented in 1BM 
Virtual Machine Facility/370: System Programmer’s Guide and IBM 
Virtual Machine Facility/370: Planning and System Generation Guide. 


Requirements for Installation | 
The facilities required for installing VS APL under VM/370 (CMS) are: 
« A System/370 machine configuration that can support VM/370 (CMS). 


« An installed release of VM/370 (CMS) of the required level or later: 
Release 3 (Program Level Change 1) if installing VS APL as a shared 
system; Release 2 (Program Level Change 13) if installing VS APL as a 
non-shared system. PTF number V03314 must be applied to CMS if it is 
not included in the release. 


e A virtual machine large enough to install VS APL (see “Virtual Storage 
Requirements’’). 


« A magnetic tape device. 
¢ The VS APL distribution tape. 


e A CMS A-disk large enough to contain the VS APL distributed files (see | 
‘Auxiliary Storage Requirements’’). 


« A CMS Y-disk large enough to contain the generated VS APL system (see 
“Auxiliary Storage Requirements”’). . 


¢ If installing VS APL as a shared system, space on a CP-owned DASD 
volume for the system (see ‘‘Auxiliary Storage Requirements’’). 


e A terminal supported by CMS. 
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Overview of Installation Procedure 


In brief, the procedure for installing VS APL under VM/370 (CMS) is as 
follows. The procedure is described in detail in the next section. 


Installation Procedure 


nH nr & W 


. Plan and define the CMS disks required for VS APL. 
. If installing VS APL as a shared system, plan the system’s load address and 


DASD space allocation. 


. Log on to VM/370 and IPL CMS. 

. Access and prepare the A-disk and the Y-disk. 

. Access the distribution tape. 

. Transfer file APLINSTL EXEC (the CMS procedure that builds VS APL) 


from the distribution tape to the A-disk. 


. Build VS APL by executing procedure APLINSTL. 
. If installing VS APL as a shared system, define, load, and save the system. 


. Test that VS APL is installed correctly by executing the sample terminal 


session (see Appendix B). 


. Plan the disk arrangement for the VS APL system, and define the disks as 


described in JBM Virtual Machine Facility/370: Operator’s Guide. Two 
disks are required: 


e One which is accessed as the A-disk during execution of the installation 
procedure. It will contain all the files transferred from the distribution 
tape and the module files created in step 7. The minimum space required 
is shown in “Auxiliary Storage Requirements.” Additional space should 
be allocated for future maintenance. At completion of the procedure, 
the A-disk should be kept as backup. 


e« One which is accessed as the Y-disk during execution of the installation 
procedure. It will contain the generated VS APL system. The minimum 
space required is shown in “‘Auxiliary Storage Requirements.” 
Additional space should be allocated for public workspaces other than 
those distributed. The Y-disk will be accessed by VS APL users. It 
should be defined with a write password known only to those who are 
responsible for installing and maintaining VS APL. 


. If installing VS APL as a shared system, decide what the load address of 


the shared system will be. The address must be larger than the largest 
virtual machine of any VS APL user; the shared system must not overlay 
any other saved segment that will be attached at the same time as VS APL. 
The load address should not be unnecessarily high; if it is, real storage is 
wasted for unreferenced CP segment table entries. During step 7 of the 
installation procedure, enter the load address when prompted to do so. 


Also allocate permanent space on a CP-owned DASD volume to contain 
the saved system. For the space required, see “‘Auxiliary Storage 
Requirements.” 


. Log on to VM/370 and IPL CMS with a virtual machine large enough to 


install VS APL (see “‘Virtual Storage Requirements’’). 
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4. Access the A-disk and the Y-disk in read/write mode. If the disks are 
newly allocated, format them using the CMS FORMAT command. 


If the disks are not newly allocated, issue the CMS LISTFILE command, 
and check that no files with the identifications listed below exist. If there 
are any such files, rename them; otherwise they will be replaced in steps 6 
and 7. The files that are created on each disk are: 


Filename Filetype Disk 
APL EXEC A and Y 
APL MODULE A and Y 
APLCVCMS EXEC A and Y 
APLCVCMS MODULE Aand Y 
APLCVRPQ EXEC A and Y 
APLCVRPQ MODULE A and Y 
APLIBTAB APLIBTAB A and Y 
APLMAC MACLIB A and Y 
APL100 TEXT A and Y 
APL101 TEXT A and Y 
APL110 TEXT A and Y 
APL111 TEXT A and Y 
APL123 TEXT A 
APLMAIN MODULE Al 

APL MAP A 
APLCVCMS MAP A. 
APLCVRPQ MAP A 
macro-name2 MACRO A 
APLINSTL EXEC A 
module-name3 TEXT A 
APFNS W0000002 a 
APLCOURS Ww0000001 Y 
CONVERT -Wo000001 Y 
EXAMPLES W0000001 Y 
FORMAT W0000001 Y 
HOWEDITS W0000001 Y 
MEDIT Ww0000001 Y 
NEWS Ww0000001 Y 
PLOT W0000001 Y 
PRINT W0000002 Y 

SBIC W0000001 Y 
SEDIT Wwo0000001 Y 
TYPEDRIL W0000001 a 
WSFNS Ww0000001 Y 


1 Created only when VS APL is installed as a shared system. 
2 There is a macro file for each macro listed in Appendix A under “Auxiliary Processor Macros.” 


3 There is a text file for each module listed in Appendix A under “CMS Executor Modules,” “Interpreter 
Modules,” “Shared Storage Manager Modules,” and “CMS Conversion Modules.” 


5. Ask the system operator to mount the distribution tape and to attach the 
tape drive as virtual device 181, 182, 183, or 184. 
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6. Transfer file APLINSTL EXEC (the CMS procedure that builds VS APL) 
from the distribution tape to the A-disk by issuing these CMS commands: 


TAPE REW (address 
TAPE FSF 3 (address 
TAPE LOAD * * A (address 


address 
is the symbolic tape identification or the address of the device on which 
the distribution tape is mounted. 


7. Invoke the procedure that builds VS APL by issuing this CMS command: 
APLINSTL 


The procedure is conversational; enter information when prompted to do 
so. The procedure performs the following actions: 


| a. Transfers all required text, exec and macro files (distribution tape files 5 
and 6) from the distribution tape to the A-disk. 


b. Transfers the distributed workspace files from the distribution tape to 
the Y-disk (workspaces VSFILES, VSAPLFILE and FULLSCREEN 
which are used only under VSPC, are not transferred). 


c. Generates file APLMAC MACLIB from the auxiliary processor macros. 
d. Copies the following files from the A-disk to the Y-disk: 
e APL EXEC (VS APL startup procedure) 


« APLCVCMS EXEC (APL\360 and APLSV conversion program 
procedure) 


« APLCVRPQ EXEC (APL/CMS conversion program procedure) 
e APLIBTAB APLIBTAB (library table file) 


« APL100 TEXT, APL101 TEXT, APL110 TEXT, APL111 TEXT, 
| and APL123 TEXT (auxiliary processors) 


e APLMAC MACLIB (auxiliary processor macro library) 


e. Creates files APL MODULE (initialization routine and auxiliary 
processor translate tables for shared system; executor, interpreter, and 
shared storage manager for non-shared system), APLMAIN MODULE 
(executor, interpreter, and shared storage manager for shared system), 
APLCVCMS MODULE (APL\360 and APLSV conversion program), 
and APLCVRPQ MODULE (APL/CMS conversion program). 


-f. Copies files APL MODULE, APLCVCMS MODULE, and 
APLCVRPQ MODULE from the A-disk to the Y-disk. 


A REGEN option, which is available in response to a prompt, causes the 
procedure the perform only actions e and f. The REGEN option can be 
used to recreate the module files after updated text files have been copied 
to the A-disk or to recreate a shared system at a different load address. 
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8. If installing VS APL as a shared system, define the system to CP and then 
load it and save it as follows: 


a. Define the system to be saved by adding a NAMESYS macro to your 
installation’ss DMKSNT ASSEMBLE module. Code the macro as 
follows: 


APLMAIN NAMESYS SYSNAME=APLMAIN, 
SYSSIZE=172K, 
VSYSADR=IGNORE, 
VSYSRES=, 
SYSCYL=, 
SYSVOL=serial-number,! 
SYSSTRT=(cylinder,page),? 
SYSPGCT=48, 
SYSPGNM=( 128-175),3 
SYSHRSG=(8,9,10)3 

| Provide the serial number of the volume on which space was allocated in step 2. 

2 Provide the starting cylinder and page address of the space allocated in step 2. 


3 The page and segment numbers shown are based on a load address of 512K. Provide the numbers 
that correspond to the load address you selected in step 2. 


b. Assemble the new system name table (DMKSNT) by using the 
GENERATE EXEC procedure as described in JBM Virtual Machine 
Facility/370: Planning and System Generation Guide. 


c. Using a virtual machine large enough to contain the system to be saved 
(load address plus 400K), load the system and save it: 


LOADMOD APLMAIN 
SAVESYS APLMAIN 


d. Before continuing with step 9, log on to VM/370 with a smaller virtual 
machine (of a size no greater than the saved system’s load address). 


9. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix B). 


This completes the installation procedure. The A-disk should be kept for 
backup and maintenance of the system. The distributed workspaces must be 
kept on the Y-disk; that is, on the disk that is accessed as a Y-disk by VS 
APL users. The other files on the Y-disk (see list in step 4 above) can also be 
kept there or they can be transferred to the CMS system disk. 
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INSTALLING VS APL UNDER OS/VS (VSPC) 


This section describes how to install VS APL as a foreground processor under 
either OS/VS1 (VSPC) or OS/VS2 (VSPC). 


Requirements for Installation 
The facilities required for installing VS APL under OS/VS are: 


A System/370 machine configuration that can support OS/VS1 (VSPC) 
or OS/VS2 (VSPC). 


An installed release of OS/VS1 (VSPC) or OS/VS2 (VSPC). 


OS/VS Linkage Editor; utility programs IEBPTPCH, IEHPROGM, and 
IEBUPDTE; and job control program IEFBR14. 


A region large enough to run the VSPC Service Program and the OS/VS 
Linkage Editor. 


A magnetic tape device. 
The VS APL distribution tape. 


Space in OS/VS1 SYS1.LINKLIB or OS/VS2 SYS1.LPALIB for the VS | 
APL load module (see ‘‘Auxiliary Storage Requirements”’). 


Space in OS/VS private libraries for the VS APL object decks and the 
conversion program load module (see “‘Auxiliary Storage Requirements’’). 


Space in VSPC public libraries for the distributed workspaces (see 
“Auxiliary Storage Requirements’’). 


Authorization to update OS/VS1 SYS1.LINKLIB or OS/VS2 
SYS1.LPALIB. 


Authorization as a VSPC chief administrator. 


A terminal supported by VSPC (required only to execute the sample 
terminal session). 


Overview of Installation Procedure 


In brief, the procedure for installing VS APL under OS/VS (VSPC) is as 
follows. The procedure is described in detail in the next section. 


i, 
2; 


Punch the sample JCL from the distribution tape. 


Allocate space for and catalog the data sets required for installing VS APL: 
VSAPL.OBJLIB and VSAPL.CNVTLIB. 


. Transfer object modules from the distribution tape to data set 


VSAPL.OBJLIB. 


. Link-edit the VS APL load module. 
. Link-edit the conversion program into data set VSAPL.CNVTLIB. 
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Installation Procedure 


6. Run the VSPC Service Program to define VS APL, public libraries 1 and 2, 


and the internal auxiliary processors to VSPC and to transfer the 
distributed workspaces to the VSPC libraries. 


. Test that VS APL is installed correctly by executing the sample terminal 


session (see Appendix C). 


. Punch the OS/VS sample JCL procedures from the VS APL distribution 


tape by executing the following job: 


//PUNCHJCL JOB accounting-information,MSGLEVEL=1 
// EXEC PGM=IEBPTPCH 
//SYSPRINT DD SYSOUT=A 
//SYSUT1 DD DSN=JCL, VOL=SER=APLDTR, UNIT=2400, 
jp DISP=OLD, LABEL=(3,NL), 
Jif DCB=( LRECL=80 , BLKSIZE=80 , RECFM=F ) 
//SYSUT2 DD SYSOUT=B 
//SYSIN DD * 

PUNCH 
/* 


There are six jobs in the sample JCL. The first five are used for each of the 
next five steps of the installation procedure. The last one is used to run the 


- conversion program (see ““OS/VS Workspace Conversion Program’’). 


It may be necessary to alter the sample JCL to suit your requirements. In 
each step, the sample JCL is listed, and the modifications that may be 
required are noted. In this step and in steps 3 and 6, group name 2400 is 
used as the UNIT parameter to.mean any magnetic tape device. In steps 4 
and 5, group name SYSDA is used as the UNIT parameter to mean any 
direct access device. If either of these names is not so defined for your 
installation, these parameters must be altered. 


. Allocate space for two partitioned data sets and catalog them: 


e VSAPL.OBJLIB, object module library for the executor, interpreter, 
and conversion program. 


e VSAPL.CNVTLIB, load module library for the conversion program. 
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Execution of job ALLOC from the sample JCL, altered to suit your 
requirements, accomplishes this step. Supply the information shown in 
lowercase below. 


/ /ALLOC JOB accounting-information,MSGLEVEL=1 


// EXEC PGM=IEFBR14 

//DD1 DD  DSN=VSAPL.OBJLIB,DISP=(NEW,KEEP), 

Sf VOL=SER=volser,UNIT=typeunit, 

// SPACE=(3200,(143,5,20)), 

// DCB=( LRECL=80 , BLKSIZE=3200, RECFM=FB ) 
//DD2 DD DSN=VSAPL.CNVTLIB,DISP=( NEW, KEEP), 
// VOL=SER=volser,UNIT=typeunit, 

// SPACE=(CYL,(1,1,1)) 

// EXEC PGM=IEHPROGM 


//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 
CATLG DSNAME=VSAPL.OBJLIB, VOL=typeunit=volser 
CATLG DSNAME=VSAPL.CNVTLIB, VOL=typeunit=volser 
/* 


. Transfer files 5 and 7 from the VS APL distribution tape to data set 
VSAPL.OBJLIB. Execution of job BUILDOBJ from the sample JCL, 
altered to suit your requirements, accomplishes this step. Supply the 
information shown in lowercase below. 


Each input file is a series of object modules, each preceded by a ./ ADD 
NAME= statement. The BUILDOBJ job reads the two files and writes 
each object module as a member of VSAPL.OBJLIB. 


//BUILDOBJ JOB accounting-information,MSGLEVEL=1 
// EXEC PGM=IEBUPDTE, PARM=NEW 

//SYSPRINT DD SYSOUT=A 

//SYSUT2 DD DSN=VSAPL.OBJLIB, DISP=OLD 
//SYSIN DD DSN=INTERP .OBJECT,VOL=SER=APLDTR, 


Sh UNIT=2400,DISP=(OLD, PASS ), LABEL=(5,NL), 
df DCB=( LRECL=80 , BLKSIZE=3200, RECFM=EB ) 
ay EXEC PGM=IEBUPDTE, PARM=NEW 


//SYSPRINT DD SYSOUT=A 
//SYSUT2 DD DSN=VSAPL.OBJLIB, DISP=OLD 
//SYSIN DD DSN=OSVS . DEPENDNT .OBJECT , VOL=SER=APLDTR, 


Jf UNIT=2400, DISP=OLD, LABEL=(7,NL), 
// DCB=( LRECL=80 , BLKSIZE=3200, RECFM=FB ) 
/* 
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4. Link-edit the VS APL load module. Execution of job LINKAPL from the 
sample JCL, altered to suit your requirements, accomplishes this step. The 
job contains two SYSLMOD DD statements, one to link-edit VS APL into 
SYS1.LINKLIB for OS/VS1 and another to link-edit VS APL into 
SYS1.LPALIB for OS/VS2. Remove the statement that does not apply to 
your operating system, and supply the information shown in lowercase 
below. 


The link-edit map output from this step should be saved. 


//LINKAPL JOB accounting-information,MSGLEVEL=1 
// EXEC PGM=HEWL, 


ih 

//SYSPRINT DD 
//OBJLIB DD 
//SYSLMOD DD 
//SYSLMOD DD 


PARM='RENT,NCAL, LIST,MAP, XREF' 

SYSOUT=A 

DSN=VSAPL.OBJLIB, DISP=SHR 
DSN=SYS1.LINKLIB,DISP=OLD (OS/VS1 ONLY ) 
DSN=SYS1.LPALIB,DISP=OLD (OS/VS2 ONLY ) 


//SYSUT1 DD UNIT=SYSDA,SPACE=(TRK, (40,10) ) 
//SYSLIN DD * 
INCLUDE OBJLIB(!) 


ENTRY APLPCOEX 

SETCODE AC( 1) 

NAME APLPCOEX(R) 
/* 


1 The sample JCL contains an INCLUDE statement for each module listed in Appendix A under “VSPC 
Executor Modules” and “Interpreter Modules.” 


. Link-edit the conversion program into data set VSAPL.CNVTLIB. 
Execution of job LINKCNVT from the sample JCL, altered to suit your 
requirements, accomplishes this step. Supply the information shown in 
lowercase below. 


The link-edit map output from this step should be saved. 


//UINKCNVT JOB’ accounting-information,MSGLEVEL=1 
// EXEC PGM=HEWL, PARM='NCAL,LIST,MAP, XREF,REUS' 


//SYSPRINT DD 
//OBJLIB DD 
//SYSLMOD DD 
//SYSUT1 DD 
//SYSLIN DD 


SYSOUT=A 

DSN=VSAPL.OBJLIB, DISP=SHR 
DSN=VSAPL.CNVTLIB, DISP=OLD 
UNIT=SYSDA,SPACE=( TRK,(40,10) ) 
‘“ ; 


INCLUDE OBJLIB(!) 


ENTRY COIBM 


NAME APLCVOS(R) 


/* 


1 The sample JCL contains an INCLUDE statement for each module listed in Appendix A under 
“VSPC/OS Conversion Modules.” 
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6. Run the VSPC Service Program to: 


¢« Define VS APL as a foreground processor. 


e Define public libraries 1 and 2. 


¢ Define the distributed auxiliary processors. 


¢ Transfer the distributed workspaces from the distribution tape to 
libraries 1 and 2 (workspaces APFNS and PRINT, which are used only 
under CMS, are not transferred). 


Execution of job VSPCSERV from the sample JCL, altered to suit your 
requirements, accomplishes this step. Supply the information shown in 
lowercase below. Although files 8 through 16 of the distribution tape 
contain 800-byte unblocked records, they must be described as 80-byte 
blocked records to the IMPORT function of the VSPC Service Program. 
See VSPC Installation Reference Material for a description of the VSPC 
Service Program and control statements. 


//VSPCSERV 
// 

//SXSOLDIR 
//SYSOLIB1 
//SYSOLIB2 


pf” 
//WSENS 

a 

If 
//CONVERT 
// 

7/ 
//TYPEDRIL 
ries 

Lf 
//APLCOURS 


// 


// 

/ /EXAMPLES 
T/ 

// 
//FORMAT 
Tf 

ii 
//MEDIT 
Li 

77 
//SEDIT 
// 

ae 


JOB 
EXEC 


DD 


DD 


DD 


accounting-information,MSGLEVEL=1 
PGM=ASUSPEXC, PARM=NOLIST 

DSN=name, DISP=OLD 

DSN=name, DISP=OLD 

DSN=name , DISP=OLD 
DSN=NEWS , VOL=SER=APLDTR, 

UNIT=2400 , DISP=( OLD, PASS ), LABEL=(8,NL),_ 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=EBS ) 
DSN=WSEFNS , VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD,PASS ), LABEL=(9,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=CONVERT , VOL=SER=APLDTR, 

UNIT=2400, DISP=( OLD, PASS ), LABEL=(10,NL), 
DCB=( LRECL=80 , BLKSIZE=800, RECFM=FBS ) 
DSN=TYPEDRIL, VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD, PASS ), LABEL=(11,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=EBS ) 
DSN=APLCOURS , VOL=SER=APLDTR, 

UNIT=2400 , DISP=( OLD, PASS ), LABEL=(12,NL), 
DCB=( LRECL=80 , BLKSIZE=800, RECFM=EBS ) 
DSN=PLOT, VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD, PASS ), LABEL=(13,NL), 
DCB=( LRECL=80 , BLKSIZE=800, RECFM=FBS ) 
DSN=EXAMPLES , VOL=SER=APLDTR, 

UNIT=2400 ,DISP=( OLD, PASS ), LABEL=(14,NL), 
DCB=( LRECL=80 , BLKSIZE=800, RECFM=FBS ) 
DSN=FORMAT, VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD, PASS ), LABEL=(15,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=MEDIT, VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD, PASS ), LABEL=(16,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=SEDIT,VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD, PASS), LABEL=(17,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
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//HOWEDITS DD 
tL 


//SBIC DD 


//NSAPLFIL DD 
if 
// 
//FULLSCRE DD 
77. 


// 
//SYSPRINT DD 


DSN=HOWEDITS , VOL=SER=APLDTR, 
UNIT=2400 , DISP=( OLD, PASS ), LABEL=( 18,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=SBIC, VOL=SER=APLDTR, 

UNIT=2400 , DISP=( OLD, PASS ), LABEL=(19,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=VSFILES , VOL=SER=APLDTR, 
UNIT=2400,DISP=( OLD, PASS ), LABEL=(20,NL), 
DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
DSN=VSAPLFIL, VOL=SER=APLDTR, 
UNIT=2400,DISP=OLD, LABEL=(21,NL), 

DCB=( LRECL=80 , BLKSIZE=800, RECFM=FBS ) 
DSN=FULLSCRE, VOL=SER=APLDTR, 
UNIT=2400, DISP=OLD, LABEL=(22,NL), 

DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 


SYSOUT=A 
* 


//SYSIN DD | 

AUTH chief-administrator-number/password 

DEFINE FP NAME( APL) CODE(AO) ENTRY( APLPCOEX ) 

DEFINE USER( 1) PASSWORD( password) LIBTYPE( PUBLIC C)- 
SPACE( 1000 ) PROJLIB( NONE) CONTENT( APL) INTPRMAX(60 30) 

DEFINE USER(2) PASSWORD( password) LIBTYPE( PUBLIC C)- 
SPACE( 1000) PROJLIB( NONE) CONTENT( APL) INTPRMAX(60 30) 

DEFINE AP( 121) NOPASS SSMAX( 4000000 30) 

DEFINE AP( 122) NOPASS SSMAX(4058 30) 

DEFINE AP( 123) NOPASS SSMAX( 32767 30) 

DEFINE AP( 124) NOPASS SSMAX( 4096 30) 

AUTH 1/password 

IMPORT 1 NEWS TYPE( OBJECT) CONTENT( APL ) 


IMPORT 1 WSFNS TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 CONVERT TYPE( OBJECT) CONTENT( APL) 
IMPORT 1 TYPEDRILL TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 APLCOURSE TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 PLOT TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 EXAMPLES TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 FORMAT TYPE( OBJECT) CONTENT( APL) 
IMPORT 1 MEDIT TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 SEDIT TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 HOWEDITS TYPE( OBJECT) CONTENT( APL ) 


IMPORT 1 SBIC TYPE( OBJECT) CONTENT( APL ) 

AUTH 2/password 

IMPORT 2 VSFILES TYPE( OBJECT) CONTENT( APL ) 
IMPORT 2 VSAPLFILE TYPE( OBJECT) CONTENT( APL ) 
IMPORT 2 FULLSCREEN TYPE( OBJECT) CONTENT( APL) 
/* 


. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix C). 
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INSTALLING VS APL UNDER DOS/VS (VSPC) 


This section describes how to install VS APL as a foreground processor under 
DOS/VS (VSPC). 


Requirements for Installation 
The facilities required for installing VS APL under DOS/VS are: 


\ e 


A System/370 machine configuration that can support DOS/VS (VSPC). 
An installed release of DOS/VS (VSPC). 
The following DOS/VS system and utility programs: 


— CORGZ 
— DSTRB 

—- LNKEDT 
~ MAINT 


A partition large enough to run the VSPC Service Program and the above 
utility programs. 


Two magnetic tape devices or one direct access storage device. 
The VS APL distribution tape or distribution disk. 


Space available for private relocatable libraries, core image libraries, VS 
APL object decks, and VS APL link-edited modules (see “‘Auxiliary 
Storage Requirements’’). 


Space in VSPC public libraries for the distributed workspaces (see 
‘Auxiliary Storage Requirements”’). 


Authorization as a VSPC chief administrator. 


A terminal supported by VSPC (required only to execute the sample 
terminal session). 


Overview of Installation Procedure 


In brief, the procedure for installing VS APL under DOS/VS (VSPC) is as 
follows. The procedure is described in detail in the next section. 


1. 
2: 


Punch the sample JCL from the distribution tape or distribution disk. 


If private libraries are desired, define a private relocatable library for the 
APL object decks and a private core image library for the APL foreground 
processor module and APL workspace conversion program. 


. Deblock the object decks from the distribution tape or distribution disk 


onto another tape or disk file, and catalog them into the relocatable library. 


. Link-edit the APL foreground processor and workspace conversion 


programs into the core image library. 


. Run the VSPC Service Program to define VS APL, public libraries 1 and 2, 


and the internal auxiliary processors to VSPC and to transfer the 
distributed workspaces to the VSPC libraries. 


. Test that VS APL is installed correctly by executing the sample terminal 


session (see Appendix C). 
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Installation Procedure 


1. Punch the DOS/VS sample JCL from the VS APL distribution tape by 
executing the following job: 


// JOB PNCHSAMP 

// ASSGN SYSO004, TAPE Distribution Tape 
// BSSGN SYSO05,X'OOD! 

// EXEC DSTRB 

// UDS COP 

// END 


Punch the DOS/VS sample JCL from the VS APL distribution disk by 
executing the following job: 


// JOB PNCHSAMP 

// ASSGN SYS004,unit,VOL=111111,SHR __ Distribution Disk 
// DLBL UIN, 'A5748AP1.DOSVSJCL.VSAPL' ,99/365,SD 
// EXTENT SYSO004 

// ASSGN SYSO05,X'OOD' 

// EXEC DSTRB 

// UDS COP 

// END 


There are several DOS/VS jobs in the sample JCL. It may be necessary to 
alter the sample JCL to suit your requirements. In each step the sample 
JCL is listed, and the modifications that may be required are noted. In this 
step, the word unit is used to represent the unit type of the distribution 
disk. In other steps, the words devicetype, and volserial are used to 
represent the DOS/VS device type and volume serial number, respectively. 
For those steps, you should supply the DOS/VS device type and volume 
serial number that is appropriate to your installation. The volume serial 
number of the distribution disk is always 111111. 


2. If private libraries are desired, define a private relocatable library for the 
APL object decks and a private core image library for the APL forground 
processor and APL workspace conversion program. If private libraries are 
not desired, skip to step 3. 


Execution of job ALLOCRLB from the sample JCL, altered to suit your 
requirements, can be used to define a new private relocatable library. 
Supply the information in lowercase below. . 


// JOB ALLOCRLB 

// ASSGN SYSRLB,devicetype, VOL=volserial,SHR 

// DLBL IJSYSRL,'VS APL PRIV RLB',99/365,SD 

// EXTENT SYSRLB,volserial,1,0,first-track,total-tracks 
// EXEC CORGZ 

NEWVOL RL=cylinders(directory-tracks ) 

/* 

rs 


Execution of job ALLOCCIL from the sample JCL, altered to suit your 
requirements, can be used to define a new private core image library. 
Supply the information in lowercase below. 


// JOB ALLOCCIL 
// ASSGN SYS003,devicetype, VOL=volserial,SHR 
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// DLBL IJSYSPC,'VS APL PRIV CIL',99/365,SD 

// EXTENT SYS003,volserial,1,0,first-track,total-tracks 
// EXEC CORGZ 

NEWVOL CL=cylinders(directory-tracks ) 

/* 

/& 


The space required in the relocatable and core image libraries is given in 
the section “Storage Requirements.” 


. Deblock the object decks from the distribution tape or distribution disk 
onto another (possibly temporary) tape or disk file. Clear space in the 
system or private relocatable library by deleting all VS APL object decks 
and by condensing the library. Then, catalog the deblocked object decks 
into the relocatable library. 


Execution of job TAPEDEBL from the sample JCL, altered to suit your 
requirements, accomplishes this step using a distribution tape. The 
deblocked output will be on tape. Supply the information in lowercase 
below. 


// JOB TAPEDEBL 


// ASSGN SYSO004,TAPE Input Distribution Tape 
// ASSGN SYSO005,TAPE Output Tape 

// UPSI 10100 

// EXEC DSTRB Deblock object file 

// UDS DBL 

// END 


// MTC WTM,SYSO005 

// MTC REW,SYSOO5 

* REMOVE FOLLOWING THREE CARDS IF SYSTEM RLB IS USED 
// ASSGN SYSRLB,devicetype, VOL=volserial,SHR 

// DLBL IJSYSRL,'VS APL PRIV RLB' ,99/365,SD 

// EXTENT SYSRLB 

// EXEC MAINT Delete VS APL OBJ and condense 
DELETR! 


CONDS RL 

/* : 

// ASSGN SYSIPT,SYSO05 SYSIPT is deblocked OBJ 
// EXEC MAINT Catalog deblocked OBJ 
/& 


Execution of job DISKDEBL from the sample JCL, altered to suit your 
requirements, accomplishes this step using a distribution disk. The 
deblocked output will be on disk. Supply the information in lowercase 
below. 


// JOB DISKDEBL 

// ASSGN SYS004,devicetype, VOL=111111,SHR 

// DLBL UIN, 'AS748AP1.DOSVSOBJ.VSAPL' , '99/365,SD 
// EXTENT SYSO04 

// ASSGN SYSO005,devicetype, VOL=volserial,SHR 

// DLBL UOUT, 'VSAPL.DEBLK.OBJECT',,SD 

1 The sample JCL contains a DELETR statement for each module listed in 


Appendix A under “VSPC Executor Modules,” “Interpreter Modules,” and 
“VSPC/DOS Conversion Modules.” 
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// EXTENT SYSO005,volserial,1,0,first-track,total-tracks 
// EXEC DSTRB 

// UDS DBL Deblock object file 

// END 

* REMOVE FOLLOWING THREE CARDS IF SYSTEM RLB IS USED 

// KSSGN SYSRLB,devicetype,VOL=volserial,SHR 

// DLBL IJSYSRL,'VS APL PRIV RLB',99/365,SD 

// EXTENT SYSRLB 


// EXEC MAINT Delete VS APL object and condense 
DELETRI 
CONDS RL 

/* 

// ASSGN SYSO06,SYSIPT Store SYSIPT for later restoration 


// DLBL IJSYSIN, 'VSAPL.DEBLK.OBJECT' 
// EXTENT SYSIPT 


ASSGN SYSIPT,SYS0O05 SYSIPT is deblocked object 
// EXEC MAINT Catalog deblocked object 
CLOSE SYSIPT,UA 
ASSGN SYSIPT,SYSO06 | Restore SYSIPT 
/& 


! The sample JCL contains a DELETR statement for each module listed in Appendix A under “VSPC 
Executor Modules,” “Interpreter Modules,” and “VSPC/DOS Conversion Modules.” 
4, Link-edit the VS APL foreground processor and workspace conversion 
modules into the core image library. 


Execution of job LINKAPL, altered to suit your requirements, 
accomplishes this step. This job will first delete the appropriate phases and 
then condense the core image library. You should remove the appropriate 
ASSGN, DLBL, and EXTENT statements from the sample JCL if the 
system core image library or the system relocatable library is to be used. 
Supply the information in lowercase below. 


// JOB LINKAPL 

* REMOVE FOLLOWING THREE STATEMENTS IF 

* SYSTEM CORE IMAGE LIB IS USED 

// DLBL IJSYSPC,'VS APL PRIV CIL',,SD 

// EXTENT SYSCLB 

ASSGN SYSCLB,devicetype,VOL=volserial,SHR 
// EXEC: MAINT 

'DELETC APLPCOEX, APLCVDOS 

CONDS CL 
/* 

* REMOVE FOLLOWING THREE STATEMENTS IF 2 
* SYSTEM RLB IS USED 
// ASSGN SYSRLB,devicetype,VOL=volserial,SHR 
// DLBL IJSYSRL,'VS APL PRIV RLB',,SD 
// EXTENT SYSRLB 
// OPTION CATAL 
ACTION REL,CLEAR,MAP,NOAUTO  VSPC/DOS workspace conversion 
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PHASE APLCVDOS,S,NOAUTO modules 
~ INCLUDE! 


ENTRY COIBM 
PHASE APLPCOEX,S,NOAUTO VS APL foreground processor 
INCLUDE? 


ENTRY APLPCOEX 
/* 
// EXEC LNKEDT 
/& 


1 The sample JCL contains an INCLUDE statement for each module listed in Appendix A under 
“VSPC/DOS Conversion Modules.” ; 


2 The sample JCL contains an INCLUDE statement for cach module listed in Appendix A under “VSPC 
Executor Modules” and “Interpreter Modules.” The INCLUDE statements are ordered to minimize 
paging. 


. Run the VSPC Service Program to: 

¢« Define VS APL as a foreground processor. 
¢ Define public libraries | and 2. 

e Define the distributed auxiliary processors. 


¢ Transfer the distributed workspaces from the distribution tape or disk to 
libraries 1 and 2 (workspace APFNS and workspace PRINT, which are 
used only under CMS are not transferred). 


Execution of job VSPCSRVT from the sample JCL, altered to suit your 
requirements, accomplishes this step for the distribution tape. Execution of 
job-VSPCSRVD, similarly altered, accomplishes this step for the 
distribution disk. Supply the information in lowercase below. (The term 
‘file-id’ represents the identification of the file, such as the VSAM master 
catalog or VSPC directory, that was assigned when VSPC was installed.) 
Both of these jobs assume that the VSAM master catalog was permanently 
assigned at IPL time and that you are using a VSAM user catalog. The user 
catalog, the VSPC directory, and VSPC library data sets are assumed to 
reside on the same volume (which is assigned arbitrarily to SYSO01). See 
VSPC Installation Reference Material for a description of the VSPC 
Service Program and VSPC libraries. 


// JOB VSPCSRVT 

// OPTION LISTX 

// BSSGN SYSO004,TAPE Distribution tape 
// MTC REW,SYSOO4 

// MTS FSF,SYSO004,7 

// DLBL IJSYSCT,'file-id',,VSAM VSPC master catalog 
// EXTENT SYSCAT 

// ASSGN SYS001,devicetype,VOL=volserial VSPC library disk 
// DLBL IJSYSUC, 'file-id',,VSAM VSAM user catalog 
// EXTENT SYSOO1 

// DLBL IJSYSOD, 'file-id',,VSAM VSPC directory 

// EXTENT SYSOO1 , 

// DLBL IJSYSO1,'file-id',,VSAM — VSPC library 

// EXTENT SYSOO1 

// DLBL IJSYSO2,'file-id',,VSAM VSPC library 
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// EXTENT SYSOO1 

// EXEC ASUSPEXC 

AUTH chief-administrator-number/password 

DEFINE FP name( APL) CODE( AO) ENTRY( APLPCOEX ) 

DEFINE USER( 1) PASSWORD( password) LIBTYPE( PUBLIC C)- 
SPACE( 1000) PROJLIB( NONE ) CONTENT( APL ) INTPRMAX(60 30) 

DEFINE USER( 2) PASSWORD( password) LIBTYPE( PUBLIC C)- 
SPACE( 1000) PROJLIB( NONE) CONTENT( APL) INTPRMAX(60 30) 

DEFINE AP( 121) NOPASS SSMAX( 4000000 30) 

DEFINE AP( 122) NOPASS SSMAX( 4058 30) 

DEFINE AP( 123) NOPASS SSMAX( 32767 30) 

DEFINE AP( 124) NOPASS SSMAX( 4096 30) 

ENVIRONMENT DEVICE( 2400 004 NOREWIND ) NOLABEL- 
FORMAT( F) BLOCKSIZE( 800) RECORDSIZE( 80 ) 

AUTH 1/password 

IMPORT 1 NEWS TYPE( OBJECT ) CONTENT( APL ) 


IMPORT 1 WSFNS TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 CONVERT TYPE( OBJECT ) CONTENT( APL ) 
IMPORT 1 TYPEDRILL TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 APLCOURSE TYPE( OBJECT ) CONTENT( APL ) 
IMPORT 1 PLOT TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 EXAMPLES TYPE( OBJECT) CONTENT( APL) 
IMPORT 1 FORMAT TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 MEDIT TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 SEDIT TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1-HOWEDITS TYPE( OBJECT) CONTENT( APL) 


IMPORT 1 SBIC TYPE( OBJECT ) CONTENT( APL ) 

AUTH 2/password ~ 

IMPORT 2 VSFILES TYPE( OBJECT) CONTENT( APL) 
IMPORT. 2 VSAPLFILE TYPE( OBJECT ) CONTENT( APL ) 
IMPORT 2 FULLSCREEN TYPE( OBJECT) CONTENT( APL) 
/* 

/& 


// JOB VSPCSRVD 

// OPTION LISTX 

// ASSGN SYS004,devicetype, VOL=111111,SHR 

// DLBL NEWS, 'A5748AP1.NEWS.VSAPL' ,99/365,SD 

// EXTENT SYSOO4 

// DLBL WSFNS, 'A5748AP1.WSFNS.VSAPL' ,99/365,SD 

// EXTENT SYSOO4 

// DLBL CONVERT, 'A5748AP1.CONVERT.VSAPL' ,99/365,SD 
// EXTENT SYSOO4 

// DLBL TYPEDRI, 'A5748AP1.TYPEDRIL.VSAPL' ,99/365,SD 
// EXTENT SYSO04 

// DLBL APLCOUR, 'A5748AP1.APLCOURS.VSAPL' ,99/365,SD 
// EXTENT SYSOO4 

// DLBL PLOT, 'A5748AP1.PLOT.VSAPL' ,99/365,SD 

// EXTENT SYSO04 

// DLBL EXAMPLE, 'A5748AP1.EXAMPLES.VSAPL' ,99/365,SD 
// EXTENT SYSOO4 

// DLBL FORMAT, 'A5748AP1.FORMAT.VSAPL' ,99/365,SD 

// EXTENT SYSOO04 

// DLBL MEDIT, 'A5748AP1.MEDIT.VSAPL' ,99/365,SD 

// EXTENT SYSOO4 
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// DLBL SEDIT, 'AS748AP1.SEDIT.VSAPL' ,99/365,SD 

// EXTENT SYSO04 

// DLBL HOWEDIT, 'A5748AP1.HOWEDITS.VSAPL' ,99/365,SD 
// EXTENT SYSO04 

// DLBL SBIC,'A5748AP1.SBIC.VSAPL' ,99/365,S 

// EXTENT SYSOO04 

// DLBL VSFILES, 'A5748AP1.VSFILES.VSAPL' ,99/365,SD 
// EXTENT SYSOO4 

// DLBL VSAPLFI, 'AS748AP1.VSAPLFIL.VSAPL' ,99/365,SD 
// EXTENT SYSO0O4 

// DLBL FULLSCR, 'AS748AP1.FULLSCRE.VSAPL' ,99/365,SD 
// EXTENT SYSOO4 es 
// DLBL IJSYSCT,'file-id',,VSAM VSAM master catalog 
// EXTENT SYSCAT 

// ASSGN SYS001,devicetype, VOL=volserial VSPC library disk 


// DLBL IJSYSUC,'file-id',,VSAM VSAM user catalog 
// EXTENT SYSOO1 

// DLBL IJSYSOD, 'file-id',,VSAM VSPC directory 
// EXTENT SYSO001,volserial 

// DLBL IJSYSO1,'file-id',,VSAM VSPC library 

// EXTENT SYSO0O1,volserial 

// DLBL IJSYSO2,'file-ia@',,VSAM VSPC library 


// EXTENT SYSOO1,volserial 

// EXEC ASUSPEXC 

AUTH chief-administrator-number/password 

DEFINE FP NAME(APL) CODE(AO) ENTRY( APLPCOEX ) 

ENVIRONMENT DEVICE( distribution-device) FORMAT( FB )- 
BLOCKSIZE( 800 ) RECORDSIZE( 80 ) | 

DEFINE USER( 1) PASSWORD( password) LIBTYPE( PUBLIC C)- 
SPACE( 1000) PROJLIB( NONE) CONTENT( APL) INTPRMAX( 60 30) 

DEFINE USER(2) PASSWORD( password) LIBTYPE( PUBLIC C)- 
SPACE( 1000) PROJLIB( NONE) CONTENT( APL) INTPRMAX(60 30) 

DEFINE AP( 121) NOPASS SSMAX( 4000000 30) 

DEFINE AP( 122) NOPASS SSMAX( 4058 30) 

DEFINE AP( 123) NOPASS SSMAX( 32767 30) 

DEFINE AP( 124) NOPASS SSMAX( 4096 30) 

AUTH 1/password 

IMPORT 1 NEWS TYPE( OBJECT ) CONTENT( APL ) 

IMPORT 1 WSFNS TYPE(OBJECT) CONTENT( APL ) 


IMPORT 1 CONVERT TYPE( OBJECT) CONTENT( APL) 
IMPORT 1 TYPEDRILL TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 APLCOURSE TYPE (OBJECT) CONTENT( APL ) 
IMPORT 1 PLOT TYPE( OBJECT) CONTENT( APL) 
IMPORT 1 EXAMPLES TYPE( OBJECT) CONTENT( APL) 
IMPORT 1 FORMAT TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 MEDIT TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1 SEDIT TYPE(OBJECT ) CONTENT( APL ) 
IMPORT 1 HOWEDITS TYPE( OBJECT) CONTENT( APL ) 


IMPORT 1 SBIC TYPE( OBJECT) CONTENT( APL ) 

AUTH 2/password 

IMPORT 2 VSFILES TYPE( OBJECT) CONTENT( APL ) 
IMPORT 2 VSAPLFILE TYPE( OBJECT) CONTENT( APL ) 
IMPORT 2 FULLSCREEN TYPE( OBJECT) CONTENT( APL ) 
/* 

/& 
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6. Test that VS APL is installed correctly by executing the sample terminal 
session (see Appendix C). 
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DEFINING VS APL USERS 


This section describes how to define VS APL users to VM/370 and VSPC. 


VM /370 User Directory 


Under CMS, a VS APL user is not defined as such. A VS APL user is a 
VM/370 user who has access to CMS and to VS APL and its libraries. The 
procedure for defining a VM/370 user directory entry is described in [BM 
Virtual Machine Facility/370: Operator’s Guide. When defining a directory 
entry fora VS APL user, observe these guidelines: 


The virtual machine must be large enough to execute VS APL (see 
‘Virtual Storage Requirements’’). If VS APL is installed as a shared 
system, the virtual machine size must be no larger than the load address of 
the shared system. 


The user’s CMS A-disk, in addition to whatever else he may use it for, is 
his VS APL private library. Define a disk at virtual device address 191 with 
sufficient space for anticipated workspace storage (see ‘‘Auxiliary Storage 
Requirements for Workspaces’’). 


The CMS Y-disk contains the VS APL public libraries; it can also contain 
other components of the VS APL system. Define a read-only link to this 
disk with virtual device address 19E. 


Do not define a link to a disk that contains VS APL project libraries. VS 
APL links to a project library disk dynamically as a G-disk with virtual 
device address 197. Defining a link to a project library disk could prevent 
other VS APL users from accessing project libraries. Also, do not define a 
disk with virtual device address 197 for any VS APL user. 


Define CMS as the system to be loaded when the user logs on. 
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VSPC User Profile 


Under VSPC, a VS APL user is not necessarily defined as such. A VS APL 
user is a VSPC user whose profile includes the options required for using VS 
APL. Use the VSPC DEFINE command or the VSPC Service Program 
DEFINE control statement to define a new user’s profile. Use the VSPC 
ALTER command or the VSPC Service Program ALTER control statement 
to modify an existing user’s profile. They are described fully in VSPC 
Installation Reference Material. An example of DEFINE operands for a VS 
APL user is: 


Operand Description 
USER( 123456) Defines user number and library number 123456. 
PASSWORD( MYPASS ) Defines logon password. 


LIBTYPE( PRIVATE ) User’s library is private. 


SPACE( 500 ) Maximum library space is 500 units (500,000 
bytes). 

PROJLIB( 512) User can access project library 512. 

CONTENT( APL ) When user logs on, he is under control of VS APL. 


If a CONTENT attribute other than APL is 
defined, the user can access VS APL by issuing the 
ENTER command. 


INTPRMAX(100 50) Maximum workspace size is 100 units (100,000 
bytes). Default workspace size is 50 units (50,000 
bytes). VSPC permits a default workspace size that 
is smaller than that required by VS APL. To 
activate a VS APL workspace, a user should have a 
default workspace size of at least 20 units (20,000 
bytes). 


SSMAX(1000 5) Maximum size of a single shared variable is 1000 
bytes. Maximum number of shared variables is 5. 


If the user intends to access VS APL workspaces in public or project libraries, 
the maximum workspace size must be at least as large as the maximum 
workspace size of those libraries. 


See also “Transferring Conversion Program Output to VSPC” for a 
discussion of how user profiles can be defined as a result of workspace 
conversion. 
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DEFINING AUXILIARY PROCESSORS 


This section describes how to define auxiliary processors to CMS and VSPC. 


Defining Auxiliary Processors to CMS 


Under CMS, auxiliary processors are not defined as such. An auxiliary 
processor exists as a CMS file whose filename is the name used to invoke it, 
whose filetype is TEXT, and whose filemode is any mode acceptable to CMS. 


Defining Auxiliary Processors to VSPC 


The internal auxiliary processors distributed with VS APL for use under 
VSPC are defined to VSPC during the installation procedure. They are 
identified as numbers 121 (APL VSPC file auxiliary processor), 122 
(EBCDIC VSPC file auxiliary processor), 123 (VSAM file auxiliary 

| processor) and 124 (full screen management auxiliary processor). If you have 
obtained the source code for VS APL, you can change the numbers by 
performing these actions: 


1. Modify VS APL module APLPCOAP by specifying the new numbers as 
| operands of the APAPL, APBCD, APVSAM and APFSM keywords of the 
APLPCOAP marco. Assemble the module. 


2. Link-edit the VS APL load module as described in the installation 
procedure. 


3. Execute the VSPC Service Program with DEFINE AP control statements 
to define the new numbers to VSPC (see VSPC Installation Reference 
Material). 


| 4. Specify the new numbers for APAPL, APBCD, and APVSAM as the 
values of global variables APAP, APEP, and APVSAM in distributed 
workspace 2 VSFILES. 


5. Specify the new number for APFSM as the value of global variable 
APFSM in workspace 2 FULLSCREEN. 


To define a user-written auxiliary processor to VSPC, execute the VSPC 
Service Program with a DEFINE AP control statement as described in VSPC 
Installation Reference Material. 
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VS APL PUBLIC AND PROJECT LIBRARIES 


In this section, the procedures for creating and maintaining VS APL public 
and project libraries are described. 


VS APL Libraries under CMS 


Library Table File 


Under CMS, a VS APL public or project library is a collection of workspaces 
that has the properties described in the following sections. The libraries are 
defined in a CMS file called the library table file. When VS APL is installed, 
the library table file and public libraries 1 through 999 are created; no project 
libraries are created. 


The library table file defines public and project libraries to VS APL under 
CMS. The filename and filetype of the library table file are both APLIBTAB. 
The library table file distributed with VS APL defines libraries 1 through 999 
as public. When VS APL is installed, the file is placed on the Y-disk, but it 
can reside on any disk. It is located via the standard CMS search order. 


When VS APL is invoked, the library table file is read into virtual storage. 
When a VS APL user requests access to a public or project library, the 
executor searches the file sequentially from the beginning for the specified 
library number. The information from the first matching entry is used to 
identify the library type and, if a project library, to link dynamically to the 
project library disk. 


Records in the file are 80-byte card images of free format. Fields are 
delimited by one or more blanks. There are two types of records; each defines 
a single library or a range of libraries: 


PUBLIC libnum|(first-libnum last-libnum) 
PROJECT libnum|(first-libnum last-libnum) owner device 


PUBLIC or PROJECT 
is the library type; only the first two letters are required. 


libnum 
is a library number; it can be any positive integer other than 1001 
(reserved for VS APL users’ private libraries) and no greater than seven 
digits. 

(first-libnum last-libnum) 


is a range of library numbers; the first number must be less than or equal to 
the second number. 


owner 
is the VM/370 user identification of the owner of the disk on which the 
project library resides. 


device 
is the virtual device address, as defined in the owner’s directory entry, of 
the disk on which the project library resides. 


Use the CMS editor to maintain the library table file (see JBM Virtual 
Machine Facility/370: EDIT Guide). 
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Public Libraries 


How to Create a Public Library 


How to Maintain a Public Library 


For VS APL under CMS, a public library is a collection of workspaces that 
has these properties: . 


¢ It resides on a disk that is accessed as the Y-disk. The disk can contain 
more than one public library. It must not contain project libraries. 


¢ It is defined as a public library in the library table file. For example, public 
libraries 1 through 999 are defined as: 


PUBLIC (1 999) 


e Each workspace in the library is a CMS file whose filetype is Wnnnnnnn, 
where nnnnnnn is the library number. For example, workspace 1 NEWS is 
a CMS file whose filename is NEWS and whose filetype is WO000001. 


e Any VS APL user can list, load, or copy workspaces in the library. 


e No VS APL user can save or drop workspaces in the library. The library is 
maintained with CMS commands. 


Public libraries 1 through 999 are defined in the distributed VS APL system. 
The disk that contains public libraries is defined during the installation 
procedure. 


To create a public library with a number greater than 999 or to change the 
distributed definition of public libraries, use the CMS editor to modify the 
library table file. 


Public library workspaces can be added, replaced, or deleted only by someone 
who is allowed write access to the public library disk. The maintenance 
functions are performed with CMS commands. The functions should be 
performed when no one is using VS APL. If this is not possible, notify VS 
APL users that they are not to access the Y-disk until the maintenance 
functions are completed. 


To add or replace a public library workspace: 


1. Have the VS APL user who created the workspace issue these CP and 
CMS commands to spool it to you: 


SPOOL PUNCH userid 
DISK DUMP filename filetype 


userid - 
is your VM/370 user identification. 


filename fi letype 
is the workspace identification. 


2. Access the public library disk in read/write mode and any filemode (B is 
used in the following examples). 


3. Transfer the workspace from the virtual reader to the A-disk: 


DISK LOAD 
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Project Libraries 


How to Create a Project Library 


. Copy the workspace from the A-disk to the public library disk and rename 


it. Note that the filetype of private workspaces is VSAPLWS. For example: 
COPYFILE NEWPUB VSAPLWS A = W0000003 B (REPLACE 


Specify the REPLACE option only if the workspace is intended to replace 
one with the same identification. 


To delete a public library workspace: 


1. 


Access the public library disk in read/write mode and any filemode. 


2. Erase the workspace. For example: 


ERASE NEWPUB WOO000003 B 


For VS APL under CMS, a project library is a collection of workspaces that 
has these properties: 


It resides on a disk that can be linked to dynamically as a G-disk with 
virtual device address 197. The disk can contain more than one project 
library. It must not contain public libraries. 


It is defined as a project library in the library table file. For example, 
project library 2000 which is owned by CMS user ABC1234 and resides 
on his disk at virtual device address 196 is defined as: 


PROJECT 2000 ABC1234 196 


Each workspace in the library is a CMS file whose filetype is Wnnnnnnn, 
where nnnnnnn is the library number. For example, workspace 2000 
PROJWORK is a CMS file whose filename is PROJWORK and whose 
filetype is WO002000. 


Any VS APL user who knows the read password defined for the disk can 
list, load, or copy workspaces in the library. 


Any VS APL user who knows the write password defined for the disk can 
save or drop workspaces in the library. 


To create a project library, first decide whether it is to reside on an existing 
disk or on a new disk. It must reside on a new disk if maximum access control 
is wanted. VS APL users’ access to project libraries is controlled by 
passwords associated with a disk, not with a library. 


To define the project library, use the CMS editor to add a record to the 
library table file. If the library is to reside on a new disk, define the disk as 
described in the following paragraphs; otherwise, creation of the library is 
completed. 
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The procedure for defining a disk (that is, for defining or modifying a 
VM/370 user directory entry) is described in IBM Virtual Machine 
Facility/370: Operator’s Guide. When defining a project library disk, 
observe these guidelines: 


e Define the disk in a VM/370 user directory entry that is used for no 
purpose other than to contain the definition of the project library disk(s). 
This is recommended because VS APL links to project disks dynamically 
and cannot do so if a permanent link exists. If the disk is defined in an 
active VM/370 user directory entry, that user must detach the disk each 
time he logs on. 


¢ Define passwords as required to impose the desired level of control. A VS 
APL user must specify the read password for LIB, LOAD, and COPY 
commands; the write password for SAVE and DROP commands. To allow 
uncontrolled access, define a password as ALL. 


¢ Define sufficient space for anticipated workspace storage (see “Auxiliary 
Storage Requirements for Workspaces”’). 


After the project library disk has been defined, format it using the CMS 
command FORMAT. 


How to Maintain a Project Library 


Project library workspaces can be added, replaced, or deleted by any user 
who knows the write password defined for the disk on which the project 
library resides. Maintenance is normally performed with VS APL commands 
SAVE and DROP; it can also be performed with CMS commands as 
described in ‘“‘How to Maintain a Public Library.” 


VS APL Libraries under VSPC 


Under VSPC, a VS APL public or project library is a VSPC public or project 
library that contains workspaces with a content attribute of APL. 


Use either the VSPC DEFINE command or the VSPC Service Program 
DEFINE control statement to create a public or project library (see VSPC 
Installation Reference Material). An example of DEFINE operands for a 


public library is: 

Operand Description 

USER( 3 ) Defines user number and library number 3. 
PASSWORD( XYZ ) Defines password which must be specified to 


logon as user 3 or to gain access to the library; if 
access is not to be controlled, specify NOPASS. 


LIBTYPE( PUBLIC C) Library is public; see discussion below of library 
maintenance for meaning of C. 


SPACE( 1000 ) Maximum library space is 1000 units (1,000,000 
bytes). 


CONTENT( APL ) Defines the content attribute of the workspace 
attached when a user logs on as user number 3. 


INTPRMAX(100 50) Maximum workspace size is 100 units (100,000 
bytes); default workspace size is 50 units (50,000 
bytes). 
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The maximum workspace size must be no greater than that of VS APL users 
who access workspaces in the library. 


To define a project library, specify operands as above except for the library 
type, which is PROJECT rather than PUBLIC. 


Public and project libraries are maintained by users who have the requisite: 
access to the libraries. In terms of library access, there are three types of 
users: 


¢ The library manager is the user who has logged on to VSPC by supplying 
the library number. 


« The workspace owner is the user who stored the workspace in the library. 


e Other users are those other than the library manager or workspace owner 
who are allowed to access the library. All users are allowed to access public 
libraries. Only those users whose profile definition includes the PROJLIB 
operand are allowed to access the specified project library. 


For both public and project libraries, if C is specified in the LIBTYPE 
operand when the library is defined, only the library manager can store, 
replace, or delete a workspace. If C is not specified, only the workspace 
owner can replace a workspace; either the workspace owner or the library 
manager can delete a workspace; other users can store new workspaces and 
_ thus become workspace owners. 


To store a new workspace or replace an existing one, use the VS APL 
command SAVE. To delete a workspace, use the VS APL command DROP 
or the VSPC command PURGE. 
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WORKSPACE CONVERSION 


General Information 


This section describes how to convert APL\360, APLSV, and APL/CMS 
workspaces to VS APL workspaces. Throughout this section, the term source 
APL is used to mean APL\360, APLSV, or APL/CMS. 


This section contains information that is applicable to workspace conversion 
under both CMS and VSPC unless noted otherwise. 


Pre-Conversion Considerations 


Conversion Input 


Conversion Options 


There are three items—library numbers, workspace names, and 
passwords—that may be unacceptable to CMS or VSPC. These items can be 
modified during the conversion procedure, as described later. However, they 
should be modified by the owners of the source APL workspaces before the 
workspaces are dumped. Modifying these items before rather than during the 
conversion procedure ensures that they are modified as the workspace owners 
wish them to be and simplifies the conversion procedure. 


The unacceptable items are: 
« A library number greater than seven digits. 


¢« A workspace name that contains deltas, underscored letters, lowercase 
letters, or national characters. 


« For CMS only, a workspace name longer than eight characters. 


e For VSPC only, a password that contains deltas or underscored characters. 
An invalid logon password can be altered by a VSPC administrator 
following conversion. An invalid workspace password must be modified by 
the workspace owner prior to conversion; a workspace with an invalid 
password cannot be accessed, and there is no way to alter the password. 


Input to the conversion procedure is a workspace dump tape from the source 
APL system. The tape can be multi-volume. For APL\360 and APLSV, the 
tape is produced by the source APL utility program; it can be a full dump, an 
incremental dump, or a selective dump. For APL/CMS, the tape is produced 
by the CMS TAPE DUMP command; it must contain only workspaces that 
were created on Version 2 of APL/CMS. 


There are three options that define which of the input workspaces are to be 
processed: 


Option Description 
Full All workspaces on the input tape are processed. 
Resume All workspaces on the input tape, beginning with a specified workspace, 


are processed. 


Select Only the specified workspaces are processed. 
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There are two options that define the type of conversion for the selected 


workspaces: 

Option Description 

Format Workspace is converted to the format defined for VS APL. 

Content Includes format conversion. In addition, all function statements are . 


examined for items that will not execute correctly under VS APL. Such 
items are converted to their VS APL equivalent, if there is one. The 
incompatible items, whether converted or not, are reported. 


These types of conversion are described in greater detail in VS APL for 
: CMS: Terminal User’s Guide and VS APL for VSPC: Terminal User’s 
Guide. 


Conversion Output 


Output of the conversion procedure is workspaces that can be executed by VS 
APL and a conversion report. The converted workspaces may or may not 
execute properly, depending on their content. The conversion report is 
intended for distribution to the owners of the workspaces. It gives 
information about the converted workspaces and, if content conversion was 
done, information about items that must be evaluated or modified by the 
workspace owner to ensure proper execution. 


Conversion program error messages are listed in the ““Messages”’ section. | 


Workspace Conversion under CMS 


There are two workspace conversion programs that execute under CMS: 
APLCVCMS converts APL\360 and APLSV workspaces for use under 
CMS; APLCVRPO converts APL/ CMS workspaces for use under either 
CMS or VSPC. The procedures for using the two programs are described in 
this section and are the same unless noted otherwise. 


Auxiliary Storage Required by Conversion Programs 


When converting APL/CMS workspaces for use under VSPC, a scratch tape 
and A-disk space are required. The APLCVRPO conversion program 
transfers each converted workspace to the tape and creates two files of job 
control statements on the converter’s A-disk. The tape and the punched JCL 
files are subsequently used with the VSPC Service Program as described in 
step 6 of the conversion procedure, below. The amount of A-disk space 
required is n 800-byte blocks, where n is the number of converted 
workspaces multiplied by 0.3. 


When converting APL/CMS workspaces for use under CMS, APL\360 
workspaces, or APLSV workspaces, only A-disk space is required. The 
APLCVRPQ and APLCVCMS conversion programs transform each input 
workspace to a CMS file on the converter’s A-disk. Estimate the amount of 
disk space required according to the number of workspaces to be converted, 
their size, and the amount of data they contain (see “Auxiliary Storage 
Requirements for Workspaces’’). If possible, use an A-disk with sufficient 
space for all the workspaces to be converted. This should be possible if the 
input tape is a single volume. 
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The simplest way to convert a multi-volume input tape is to segment the job 
by volume. Allocate the maximum disk space allowed by CMS (246 
cylinders) and do a separate full conversion of each volume as if it were a 
complete dump tape. Directory information, which may be present on the first 
volume of the input tape, is not needed for VS APL under CMS and is 
ignored by the conversion program. 


See the last item in step 5 of the conversion procedure for a discussion of how 
to resume conversion if it terminates abnormally because of insufficient disk 
space. 


Identification of Converted Workspaces 


When an APL \360 or APLSV workspace is converted, its identification is 
transformed to a CMS file identification. The workspace name, truncated 
from the right to eight characters, becomes the CMS filename. The library 
number, truncated from the left to seven digits or extended to the left with 
zeros to seven digits, and prefixed with a W, becomes the CMS filetype. The 
CMS filemode is always A1. For example: 


Workspace Identification CMS File Identification 

25 GENWORK GENWORK W0000025 Al 
1234567 COMPUTATION COMPUTAT W1234567 Al 
12345678 XREF XREF W2345678 Al 


When an APL/CMS workspace is converted, its identification (which is a 
CMS file identification) is retained with no change. The filetype of a private 
APL/CMS workspace is VMAPLWS. The filetype of a public APL/CMS 
workspace is Pnnnnnn, where nnnnnn is the library number. 


After workspaces have been converted, it may be necessary to change their 
identification. This can be done as part of the conversion procedure (as 
described in step 6) or by the recipients of the converted workspaces. The 
required changes are: 


¢ The filetype of private workspaces must be changed to VSAPLWS. 


« For APL/CMS workspaces only, the filetype of public libraries must be 
changed to Wnnnnnnn, where nnnnnnn is the library number. 


_e For APL/CMS workspaces only, lowercase letters or national characters 
that occur in a filename must be changed to uppercase letters or numbers. 


Workspace Conversion Procedure 


1. Log on to VM/370 and IPL CMS with a virtual machine large enough to 
execute the conversion program (see ‘‘Virtual Storage Requirements’’). 


2. Access an A-disk in read/write mode with the required amount of disk 
space (see ‘“‘Auxiliary Storage Required by Conversion Programs’’). If the 
disk is newly allocated, format it using the CMS FORMAT command. 


3. Ask the system operator to mount the workspace dump tape and to attach 
the tape drive as virtual device 181. If converting APL/CMS workspaces 
for use under VSPC, also ask the system operator to mount a scratch tape 
and to attach the tape drive as virtual device 182. 
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4. Invoke the conversion program and specify the desired options by issuing 
one of the following CMS commands: 


To invoke the APL\360 and APLSV conversion program: 
APLCVCMS [FULL|RESUME|SELECT] [CONTENT |NOCONTENT] 


The meaning of the operands is described in ‘Conversion Options’’; 
NOCONTENT selects the format option. The operands can be 
truncated down to their initial character. The sequence in which the two 
operands are entered is immaterial. The default operands are FULL and 
CONTENT. 


To invoke the APL/CMS conversion program: 
APLCVRPQ [FULL|RESUME] [CONTENT |NOCONTENT] 


The operands are as described above. Note that the SELECT option is 
not supported. 


5. The conversion procedure is conversational. Enter information as 
explained below when prompted to do so. If the information is an APL 
workspace identification, represent APL characters with EBCDIC 
characters as follows: 


APL EBCDIC 

0-9 0-9 

A-Z a-z (lowercase) 
A-Z A-Z (uppercase) 
A * 

A $ 


Note that when the conversion program prints a workspace identification 
as part of a prompt, it uses A-Z to represent A - Z and a-z to represent 


A 
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2. 


If the input option is RESUME, enter the identification of the 
workspace at which conversion is to begin as: 


library-number workspace-name 


If the input option is SELECT, enter a list of the workspaces to be 
converted. The list can have up to 100 entries. Each entry can be one of 
the following: 


library-number workspace-name 
to select a specific workspace. 


library-number 
to select all workspaces in a specific library. 


Press the RETURN key after each entry. Press the RETURN key alone 
to terminate the list. Entries in the list that are not found on the input 
tape are ignored. 


If converting APL/CMS workspaces, enter YES or NO (depending on 
the destination of the converted workspaces) in response to this prompt: 


IS OUTPUT FOR VSPC (YES|NO) 


e If aCMS file identification duplicates that of a file already on the 
A-disk, enter one of the following options: 


Option Description 


RENAME Give the workspace a new name. In response to the 
next two prompts for filename and filetype, enter the 
desired CMS filename and filetype or press the 
RETURN key alone to leave either one unchanged. 
Filetype, if entered, must be as described earlier (W 
followed by seven digits). 


IGNORE Reject the workspace; do not convert it. 
REPLACE Replace the existing CMS file with this one. 
CANCEL Terminate execution of the conversion program. 


e If a workspace name is invalid (contains deltas or underscored letters), 
enter the RENAME, IGNORE, or CANCEL option as described in the 
preceding step. 


e When end of volume is reached, either enter CANCEL to terminate 
execution of the conversion program, or do the following to continue 
with the next volume: 


— Enter CP mode by pressing the ATTN key twice, (or press the PA1 
key if an IBM 3270 terminal is being used). 


~— Use the CP command MSG to ask the system operator to mount the 
next volume on the tape drive attached as virtual device 181. 


— Type the CP command BEGIN. 
— Type RESTART. 


e If the conversion program terminates abnormally because the A-disk is 
full or because of an unrecoverable error, the last partially converted 
workspace is erased from the A-disk and its identification is printed at 
the terminal. Process the workspaces that have been converted by doing 
step 6 of the conversion procedure. Then rewind the input tape by 
issuing this CMS command: 


TAPE REW 


and resume the conversion procedure at step 4. Specify the RESUME 
option and the identification of the workspace that was printed when 
the conversion program terminated. 


6. When the conversion program has completed execution, process the 
converted workspaces according to their destination: 


¢ If the converted workspaces are to be used with VS APL under CMS 
and are not owned by the converter, separate the conversion report into 
sections by library number and distribute the sections to their owners. 
Disperse the converted workspaces to their owners and erase them from 
the A-disk by doing one of the following: 


— To change the filetype of APL\360 or APLSV private workspaces to 
VSAPLWS before dispersing them, use the CMS editor to create a 
file named NEWTYPE EXEC containing these statements: 


&CONTROL ERROR 
RENAME 6&1 &2 &3 = VSAPLWS = 
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Then issue these CP and CMS commands for each owner: 


SPOOL PUNCH userid 

LISTFILE * filetype A (EXEC 
CMS NEWTYPE 

LISTFILE * VSAPLWS A (EXEC 
CMS DISK DUMP 

CMS ERASE 


userid 
is the owner’s VM/370 user identification. 


filetype 
is that of the owner’s workspaces in the form Wnnnnnnn; it can be 
obtained from the conversion report. 


— To disperse APL\360 or APLSV workspaces without changing their 
filetype, issue these CP and CMS commands for each owner: 


SPOOL PUNCH userid 

LISTFILE * filetype A (EXEC 
CMS DISK DUMP 

CMS ERASE 


The operands are as described above. 


— To disperse APL/CMS workspaces, issue these CP and CMS 
commands for each workspace: 


SPOOL PUNCH userid 
DISK DUMP filename filetype 
ERASE filename filetype 


userid 
is the owner’s VM/370 user identification. : 


filename filetype 
is the identification of the APL/CMS workspace. 


If the converted workspaces are to be used with VS APL under CMS 
and are owned by the converter, the conversion procedure is completed 
except for changing the filetype. 


To change the filetype of all private workspaces, issue this CMS 
command: 


RENAME * filetype A = VSAPLWS = 


filetype 
is either that generated for APL\360 and APLSV workspaces in the 
form Wnnnnnnn, where nnnnnnn is the source APL library number; 
or VMAPLWS for APL/CMS workspaces. 


To change the filetype of APL/CMS public workspaces, issue this CMS 
command: 


RENAME * Pnnnnnn A = Wnnnnnnn = 


nnnnnn 
is the APL/CMS library number; note that the new filetype has an 
additional zero to the left. 


e If the converted workspaces are APL/CMS workspaces to be used 
under VSPC, use the output of the conversion program as input to the 
IMPORT function of the VSPC Service Program. 


There are two JCL files on the A-disk. The file named IMPORT 
DDCARDS contains the DD statement shown below for each converted 
workspace. The file named IMPORT COMMANDS contains the 
IMPORT statement shown below for each converted workspace. 


//adname DD DSN=wsname, UNIT=2400 , LABEL=(n,NL), 
// VOL=SER=XXXX, DISP=(OLD, PASS), 
// _DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 


IMPORT wsname FROM( ddname ) TYPE( OBJECT ) CONTENT( APL ) 


ddname 
is M1 through Mn, where n is the number of converted workspaces. 


wsname 
is the workspace name (the CMS filename). 


n 
is the position of the workspace on the output tape. 


The JCL files must be modified before they are used to run the VSPC 
Service Program. Use the CMS editor to modify them before printing 
and punching them, or modify them manually afterward. The required 
modifications are: 


— Add the JCL statements required by the service program. 
— Add an AUTH control statement. 


— Ineach DD statement, change XXXX to the serial number of the 
output tape. 


— If the output tape has standard labels, change the LABEL 
subparameter NL in each DD statement to SL. 


— If lowercase letters or national characters occur in a workspace name, 
change them to uppercase letters or numbers in the DD and IMPORT 
statements. 


— If the workspaces are to be transferred to VSPC libraries other than 
that specified in the AUTH control statement, insert the library 
number in each IMPORT statement preceding wsname. 


— If the VSPC host system is DOS/VS, use the information in file 
IMPORT DDCARDS to prepare the required TLBL statements. 


Print and punch the files by issuing these CMS commands: 


PRINT IMPORT DDCARDS 
PRINT IMPORT COMMANDS 
PUNCH IMPORT DDCARDS 
PUNCH IMPORT COMMANDS 


Send the output tape, the conversion report, and the printed and 
punched JCL files to the VSPC installation. 


At the VSPC installation, execute the VSPC Service Program to transfer 
the converted workspaces to VSPC libraries. IMPORT, AUTH, and the 
VSPC Service Program are described in VSPC Installation Reference 
Material. 
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Workspace Conversion under VSPC 


There is one workspace conversion program that executes under OS/VS 
(APLCVOS) and another that executes under DOS/VS (APLCVDOS). Both 
programs convert APL\360 and APLSV workspaces. The procedures for 
using the two programs are described in this section and are the same unless 
noted otherwise. The procedure for converting APL/CMS workspaces for use 
under VSPC is described in ‘“Workspace Conversion under CMS.” 


Converting workspaces to be used under VSPC is basically a three-step 
procedure: 


1. Execute the conversion program. The output is a conversion report and a 
data set which contains the converted workspaces and user profiles. 


2. Separate the conversion report into sections by library number and 
distribute the sections to their owners. 


3. Execute the VSPC Service Program with COPY control statements to 
transfer the converted workspaces to VSPC libraries and (optionally) to 
define their owners to VSPC. Input to the VSPC Service Program is the 
data set output by the conversion program. 


If the source APL dump tape contains library numbers or workspace names 
that are unacceptable to VSPC, the procedure must be executed twice. First 
do a full conversion. The unacceptable workspaces are rejected by the 
conversion program but identified on the conversion report. Then do a 
selective conversion of the rejected workspaces using information provided by 
the workspace owners to rename them. 


Conversion Control Statements 


FORMAT Statement 


Input to the conversion program is an APL\360 or APLSV workspace dump 
tape and a set of control statements as described below. All control 
statements are optional. A statement can appear anywhere within columns 1 
to 71 of a card; columns 72 to 80 are ignored; continuation is not allowed. 
The operands shown in uppercase can be truncated down to their initial 
character. Operands can be separated by blanks or parentheses. If an operand 
is an APL workspace identification, represent APL characters with EBCDIC 
characters as follows: 


APL - EBCDIC 

0-9 0-9 

A-Z A-Z (ipperease) 
AZ a-z (lowercase) 
A * 

A $ 


Use the FORMAT statement to select format conversion. Omit the statement 
to select content conversion. The syntax of the statement, which has no 
operands, is: 


FORMAT 


56 VS APL Installation Reference Material 


SELECT Statement 


RESUME Statement 


DESCRIBE Statement 


Use the SELECT statement to identify the libraries and/or workspaces to be 
converted during a selective conversion, and (optionally) to provide new 
identifications for workspaces with invalid library numbers or names. The 
maximum number of SELECT statements allowed is 100. If SELECT 
statements are included, RESUME is not allowed. For full conversion, omit 
both SELECT and RESUME statements. 


The syntax of the statement is: 
SELECT libnum [newlibnum] [wsname [newwsname] ] 


libnum 
is the library number of the source APL workspace. 


newlibnum 
is the VSPC library number; if omitted, the library number is 1ibnum. The 
number cannot exceed seven digits. 


wsname 
is the name of the source APL workspace; if omitted, all workspaces in the 
specified library are selected. 


newwsname 
is the name of the workspace in VSPC; if omitted, the name is wsname. 
The name cannot exceed 11 characters and cannot contain deltas or 
underscored letters. 


Use the RESUME statement to identify the workspace at which conversion is 
to resume. If RESUME is used, SELECT statements are not allowed. For full 
conversion, omit both RESUME and SELECT statements. 


The syntax of the statement is: 
RESUME libnum wsname 


libnum 
is the library number of the source APL workspace. 


wsname 
is the name of the source APL workspace. 


Use the DESCRIBE statement to supply library space and shared variable 
space values. Only one DESCRIBE statement is allowed. The values apply to 
all libraries processed by the conversion program. 


The syntax of the statement is: 
DESCRIBE [LSPACE n] [SHARE m] 


LSPACE n . 
is the maximum size of a library; n is units of 1000 bytes. 


SHARE m 
is the maximum size of a shared variable; m is units of 1000 bytes. 
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The conversion program determines library space for each user as follows: 


e If the input tape contains directories, the LSPACE operand of the 
DESCRIBE statement is ignored. The conversion program computes 
LSPACE according to the user’s source APL wotreness size (WSSIZE) 
and quota (WSQUOTA) as follows: 


X+20480f 614441.1xWSSIZE 
Greater of 20K and source WS size plus 10% plus 6144 for internal 
buffers 


X*2048x1p0 2048T2047+X 
Rounded to nearest 2K 


VSPCSIZE+1p0 1000T999+X 
Rounded to nearest 1000 and converted to units of 1000 


LSPACE*VSPCSIZEXWSQUOTA 
Multiplied by workspace quota 


¢ If the input tape has no directories, LSPACE is as specified in the 
DESCRIBE statement. There are no directories if the input tape is a 
selective dump, or if it is multi-volume and the first volume is not input to 
the conversion program. 


e If there is no DESCRIBE statement, or if LSPACE is not specified, 
LSPACE is 500 units. 


The conversion program specifies each user’s maximum shared variable size 
to be either that specified in the DESCRIBE statement or 0. It is the specified 
SHARE value if the input tape contains directories, the user’s directory 
indicates a shared variable quota other than 0, and a SHARE value is 
specified in the DESCRIBE statement. In all other cases, SHARE is 0. For 
APL \360, which does not support shared variables, the SHARE value 
resulting from conversion is always 0. 


Note that APLSV defines the number of shared variables that a user can 
have, but does not restrict the size of a shared variable. Therefore, if a 
SHARE value is not defined to the conversion program and not otherwise 
defined to VSPC, or if the SHARE value is inadequate, a user who migrates 
to VS APL from APLSV will not be able to execute functions that use shared 
variables. 
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OS/VS. Workspace Conversion Program 


Execution of job CONVERT from the sample OS/VS JCL distributed with 
VS APL can be used to run the OS/VS conversion program. Alter the job to 
suit your requirements as noted below. 


/ /CONVERT JOB REGION=valuel!l 

// EXEC PGM=APLCVOS 

//STEPLIB DD DSN=VSAPL.CNVTLIB, DISP=SHR 

//APLTLBL DD DSN=dsname, VOL=( PRIVATE, ,SER=volser ), 


ii. UNIT=2400, DISP=OLD, LABEL=( 1,BLP )2 
//APLTDTA DD DSN=dsname, VOL=( PRIVATE, ,SER=volser), 
ate UNIT=2400 , DISP=OLD, LABEL=( 2, BLP )2 

/ /APLTEOV DD DSN=dsname, VOL=( PRIVATE, , SER=volser), 
ri UNIT=2400,DISP=OLD, LABEL=( 3, BLP )? 
//APLDIRE DD UNIT=SYSDA,SPACE=( 8004,(5,5),RLSE)3 
//APLOUT DD DSN=APLOUT , VOL=SER=volser,UNIT=2400, 
// DISP=( NEW, KEEP,KEEP ), LABEL=( ,SL)4 


//APLRPRT DD SYSOUT=A,DCB=BLKSIZE=121 
//SYSUDUMP DD SYSOUT=A 


//SYSIN DD * 
Insert conversion control statementsS. 
/* . 


1 


For region size, see “Virtual Storage Requirements.” Supply other JOB parameters according to your 
requirements. 


The APLTLBL, APLTDTA, and APLTEOV DD statements describe the source APL dump tape. The 
conversion program bypasses label processing. Supply the information shown in lowercase. 


The APLDIRE DD statement describes a temporary data set used by the conversion program for directory 
entries (information about each input account number). Each 8004-byte block has space for 400 entries. 
The space allocation in the sample JCL allows for conversion of 32,000 account numbers. Modify the space 
allocation, if necessary. 


The APLOUT DD statement describes the sequential data set created by the conversion program. It can be 
tape, as described in the sample JCL, or disk. Supply the information shown in lowercase. If output to disk 
is wanted, supply the appropriate information. 


Insert conversion control statements after the SYSIN DD statement. 
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DOS/VS Workspace Conversion Program 


Execution of job CONVERT from the sample DOS/VS JCL distributed with 
VS APL can be used to run the DOS/VS conversion program. Alter the job 
to suit your requirements as noted below. 


// JOB CONVERT 

// ASSGN SYS004, TAPE! 

// ASSGN SY005, TAPE, VOL=CNVRT2 

// ASSGN SYS006,3330,VOL=volserial, SHR? 

// DLBL APLDIRE,'file-id',,SD 

// EXTENT SYS006,volserial,1,sequence,rel-track,... 
...number-of-tracks 

// EXEC APLCVDOS,SIZE=size4 

Insert conversion control statements. 

/* 

Js 


The SYS004 assignment describes the source APL dump tape. The conversion program does not perform 
DOS label processing, but reads the label as the first file. 


_ 


i) 


The SYS005 assignment describes the output tape created by the conversion. No label or leading tape mark 
is written. 


The SYS006 assignment describes a temporary data set used by the conversion program for directory 
entires. This data set must reside on a 3330 DASD device. 


For partition size, see “Virtual Storage Requirements.” 


Insert conversion control statements after the EXEC statement. 


User Profiles Created by Conversion Program 


The data set created by the conversion program contains a user profile for 
-each converted library as well as the converted workspaces. The contents of 
each user profile created by the conversion program are: 


Item Value | 


USER Source APL library number or new library number specified 
in SELECT statement. 


PASSWORD _ Source APL logon password if directories were processed by 
conversion program; otherwise NOPASS. 


LIBTYPE Public library if USER is less than 1000; users other than the 
library manager can store files in the library (C is not 
specified). Private library if USER is greater than or equal to 
1000. 


SPACE Library space quota as determined by conversion program. 
See discussion of LSPACE in ‘“‘DESCRIBE Statement.” 


CONTENT APL 
SIZE edit-size (maximum size for editable data) is 0. 


obj-size (maximum size for object programs) is 0. 


60 VS APL Installation Reference Material 


Item Value 
INTPRMAX = maximum (maximum interpreter workspace size) is: 


X*20480F 61444+1.1xXWSSIZE 
Greater of 20K and source WS size plus 10% plus 
6144 for internal buffers 


X*+X+8192 
Plus 8K 


X*2048x1p0 2048T20474+X 
Rounded to nearest 2K 


MAXIMUM<1p0 1000T999+X 
Rounded to nearest 1000 and converted to units of 
1000 


default (default interpreter workspace size) is VSPCSIZE 
(see ‘DESCRIBE Statement’’). 


SSMAX size (maximum size of a shared variable) is as determined by 
conversion program. See discussion of SHARE in 
“(DESCRIBE Statement.” 


number (maximum number of shared variables) is source 
APL shared variable quota if directories were processed by 
conversion program; otherwise 0. Always 0 for converted 


APL \360 workspaces. 
PROJLIB None 
JECODE None 
NOADM User not authorized to use VSPC administrator commands. 


Transferring Conversion Program Output to VSPC 


When a converted workspace is transferred to VSPC, it becomes a file in the 
VSPC library. Its library number is the source APL library number or the new 
library number specified in a SELECT statement. Its name is the source APL 
workspace name or the new workspace name specified in a SELECT 
statement. Its password is the source APL workspace password. 


Use the COPY control statement of the VSPC Service Program to transfer 
the conversion program output (converted workspaces and user profiles) to 
the VSPC library. Each user profile that does not exist in the VSPC library is 
inserted. If a user profile does exist in the library, the profile created by the 
conversion program is ignored. The converted workspaces are added to the 
newly defined or existing user libraries. 


If the owner of converted workspaces is a new VSPC user and if the profile 
created by the conversion program is not satisfactory, either (1) use DEFINE 
to create a user profile before transferring the conversion program output; or 
(2) use ALTER to modify the user profile after transferring the conversion 
program output. 


COPY, DEFINE, ALTER, and the VSPC Service Program are described in 
VSPC Installation Reference Material. 
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TRANSPORTING WORKSPACES BETWEEN CMS 
AND VSPC 


When transporting VS APL workspaces between CMS and VSPC, no 
conversion is required. VS APL workspaces have the same format under all 
host systems. 


Transporting Workspaces from CMS to VSPC 
1. At the CMS installation: 


a. Ask the system operator to mount a scratch tape and to attach the tape 
drive as virtual device 181, 182, 183, or 184. 


b. Access the disk(s) from which the workspaces are to be transferred in 
read/only mode. 


c. Define the output device by issuing the CMS command: 
FILEDEF OUTMOVE TAPn (RECFM F LRECL 800 BLOCK 800 


TAPn 


is the magnetic tape device where n can be 1, 2, 3, or 4 to represent 
device 181, 182, 183, or 184 respectively. 


d. Transfer the workspaces to tape by issuing these CMS commands for 
each workspace: . 


FILEDEF INMOVE DISK filename filetype filemode 
MOVEFILE 


filename filetype filemode 
is the CMS identification of the workspace. 


e. When all workspaces have been transferred to tape, rewind and unload 
the tape: 


' TAPE RUN TAPn 


2. At the VSPC installation, execute the VSPC Service Program with 
IMPORT control statements, using the tape as input, to transfer the 
workspaces to VSPC libraries. Each workspace on the tape is a separate 
data set. For OS/VS (VSPC), use one DD statement and one IMPORT 
control statement for each workspace. For DOS/VS (VSPC), use one 
IMPORT control statement for each workspace and one ENVIRONMENT 
control statement for the entire job. Although the input data sets contain 
800-byte unblocked records, they must be described as 80-byte blocked 
records to the service program. For example, to transfer the first two 
workspaces on the tape into OS/VS (VSPC) library 1002 and give them 
the names MYWS and TESTWS, use these statements: 


//MYWS DD DSN=MYWS, VOL=SER=volser,UNIT=2400, 
// DISP=( OLD, PASS ), LABEL=(1,NL), 

// DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
//TESTWS DD  DSN=TESTWS,VOL=SER=volser,UNIT=2400, 
Ti DISP=( OLD, PASS ), LABEL=(2,NL), 

// DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 


IMPORT 1002 MYWS TYPE( OBJECT ) CONTENT( APL ) 
IMPORT 1002 TESTWS TYPE( OBJECT) CONTENT( APL ) 
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To Perform the same operation for DOS/VS (VSPC), use these 
statements: 


//ASSGN SYS004, TAPE 


ENVIRONMENT DEVICE( 2400 004 NOREWIND) NOLABEL - 
FORMAT( F ) BLOCKSIZE( 800 ) RECORDSIZE( 80 ) 


IMPORT 1002 MYWS TYPE( OBJECT) CONTENT( APL ) 
IMPORT 1002 TESTWS TYPE( OBJECT) CONTENT( APL ) 


” See VSPC Installation Reference Material for a description of the 
VSPC Service Program and the ENVIRONMENT and IMPORT control 
statements. 


Transporting Workspaces from VSPC to CMS 


1. At the VSPC installation, execute the VSPC Service Program with 
EXPORT control statements to transfer the workspaces to tape. Transfer 
each workspace as an unlabeled data set containing 800-byte unblocked 
records. For OS/VS (VSPC), use one DD statement and one EXPORT 
control statement for each workspace. For DOS/VS (VSPC), use one 
EXPORT control statement for each workspace and one 
ENVIRONMENT control statement for the job. For example, to transfer 
two workspaces named MYWS and TESTWS from OS/VS (VSPC) library 
1002 as the first two data sets on the tape, use these statements: 


//MYWS DD DSN=MYWS, VOL=SER=volser , UNIT=2400 
// DISP=( OLD, PASS ), LABEL=(1,NL), 

Tf DCB=( LRECL=80 , BLKSIZE=800 , RECFM=FBS ) 
//TESTWS DD  DSN=TESTWS,VOL=SER=volser,UNIT=2400, 
// DISP=( OLD, PASS ), LABEL=(2,NL), 

// DCB=( LRECL=80, BLKSIZE=800 , RECFM=FBS ) 


EXPORT 1002 MYWS TYPE( OBJECT) CONTENT( APL) 
EXPORT 1002 TESTWS TYPE( OBJECT) CONTENT( APL ) 


To perform the same operation for DOS/VS (VSPC), use these statements: 
//ASSGN SYS004, TAPE 


ENVIRONMENT DEVICE( 2400 004 NOREWIND) NOLABEL - 
FORMAT(F) BLOCKSIZE( 800) RECORDSIZE( 80 ) 


EXPORT 1002 MYWS 
EXPORT 1002 TESTWS 


See VSPC Installation Reference Material for a description of the VSPC 
Service Program and the ENVIRONMENT and EXPORT control 
statements. 


2. At the CMS installation: 


a. Ask the system operator to mount the tape and to attach the tape drive 
as virtual device 181, 182, 183, or 184. 


b. Access the disk(s) to which the workspaces are to be transferred in 
read/write mode. 
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c. Define the input device by issuing this CMS command: 
FILEDEF INMOVE TAPn (RECFM F LRECL 800 BLOCK 800 


TAPn 
is the magnetic tape device where n can be 1, 2, 3, or 4 to represent 
device 181, 182, 183, or 184 respectively. 


d. Transfer the workspaces from tape to disk by issuing these CMS 
commands for each workspace: 


FILEDEF OUTMOVE DISK filename filetype filemode 
MOVEFILE 


filename 
is the name of the workspace. 


filetype 
is VSAPLWS if the workspace is transferred to a private library; it is 
Wnnnnnnn if the workspace is transferred to a public or project 
library, where nnnnnnn is the library number. 


filemode 
is that of the disk to which the workspace is transferred. 
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USING THE VS APL MICROCODE ASSIST 


The VS APL microcode assist, which is available for System/370 Models 135 
and 145, performs some of the functions of the VS APL interpreter. The 

procedure for loading the microcode assist is described in Operator’s Library: 
System/370 Model 135 Procedures and IBM System/370 Model 145 


Operator: Procedures. If the microcode assist is there when VS APL is 
invoked, it is detected and used. 
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STORAGE REQUIREMENTS 


Virtual Storage Requirements 


Figure 3 shows the minimum virtual machine size (VM/370), region size 
| (OS/VS), and partition size (DOS/VS) required to install and execute VS 
APL and to execute the workspace conversion programs. 


Host To Install To Execute To Execute 
System VS APL VS APL Conversion Program 
VM/370 (CMS) 400K 400K! 200K + 3.1 x WS5 for APLCVCMS 
(APL non-shared) 
200K + 2.1 x WS§ for APLCVRPQ 
VM/370 (CMS)  SSA2 + 400K 320K3 as above 
(APL shared) 
OS/VS (VSPC) 256K 185K4 124K + 3.1 x WS5 
DOS/VS (VSPC) 256K 185K4 124K + 3.1x WSS 


1 Assumes a minimum-size workspace (20K) and no auxiliary processors. To execute with all distributed 


auxiliary processors and 4K of shared memory, add 20K. For additional shared memory or larger 
workspace, increase virtual machine size correspondingly. Users who access a large number of disks and 
files may require additional storage for CMS control blocks. 


2 Where SSA is the shared system’s load address. 


3 This is the mintimum-size CMS virtual machine. It allows a 100K workspace. You can increase the size of 
the virtual machine as noted in 1 above, but must not exceed the load address of the shared system. In 
addition, 192K (3 segments) of shared main storage is required. 


This is the virtual storage required for the VS APL interpreter and executor (including the internal 
| auxiliary processors), rather than the region or partition size. It does not include virtual storage required for 
VSPC, access methods, and workspaces. 


5 Where WS is the size of each source APL workspace. 


Where WS is the size of the largest source APL workspace; virtual machine size must be at least 264K. 


Figure 3. Virtual Storage Requirements for VS APL 


Auxiliary Storage Requirements 
In this section, direct access storage devices are identified as follows: 
2314: IBM 2314 Direct Access Storage Facility and IBM 2319 Disk Storage. 
3330: IBM 3330 Disk Storage and IBM 3333 Disk Storage and Control. 
3340: IBM 3340 Direct Access Storage Facility. 


Auxiliary Storage Requirements for VS APL 


Figure 4 shows the minimum auxiliary storage required to install VS APL as a 
non-shared system under CMS. Note the columns that indicate whether the 
storage requirement applies to the A-disk, the Y-disk, or both. The total 
cylinder requirements for each disk are computed using the total block 
requirements; they are not the sum of the cylinders required for each 
component. 


Figure 5 shows a summary of the minimum auxiliary storage required to 
install VS APL as a shared system under CMS. The detail is as shown in 
Figure 4, except that component APL MODULE requires 8 blocks and there 
is an additional component, APLMAIN MODULE, that requires 232 blocks 
on the A-disk. 
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Disk 800-byte Cylinders 


Component A Y_ Blocks 2314 3330 3340 
TEXT files for executor, x 814 6 4 9 
interpreter, shared storage 

manager 

TEXT files for conversion x 256 2 1 3 
programs 

Link-edit maps x 136 1 | 
Macros x 125 1 1 
APLINSTL EXEC x 45 1 1 1 
APL MODULE x xX 285 ps 2 3 
APLCVCMS MODULE x xX 86 1 1 1 
APLCVRPQ MODULE xX X 81 1 1 1 
APL EXEC x xX 2 1 1 1 
APLCVCMS EXEC x Xx Z 1 1 1 
APLCVRPQ EXEC x xX 1 1 1 1 
Auxiliary processors x x 60 1 1 1 
APLMAC MACLIB x xX 119 1 1 2 
Library table file x xX 1 1 1 1 
Distributed workspaces x 396 3 2 5 
Total for A-disk x 2013 14 8 21 
Total for Y-disk x 1033 7 4 11 


Figure 4.. Auxiliary Storage Requirements for Non-Shared VS APL under CMS 


Cylinders 
Storage Device Unit of Storage Units Required 2314 3330 3340 
A-disk 800-byte block 2013 14 8 21 
Y-disk 800-byte block 801 8 4 9 
CP volume 4K page 49 2 1 


Figure 5. Auxiliary Storage Requirements for Shared VS APL under CMS 


Figure 6 shows the minimum auxiliary storage required to install VS APL 
under OS/VS (VSPC). The VSPC library storage requirement is for the 
distributed workspaces. 


Figure 7 shows the minimum auxiliary storage required to install VS APL 
under DOS/VS(VSPC). The VSPC library storage requirement is for the 
distributed workspaces. 


Auxiliary Storage Requirements for Workspaces 


The amount of auxiliary storage required for a workspace depends on the 
amount of data it contains, not on the size of the workspace. To compute the 
number of bytes required to store a workspace, subtract the space available, 
OWA, from the workspace size, )WSSIZE. 


Under VSPC, a VS APL workspace is a VSPC file. VSPC files are stored in 
units of 1000 bytes. . 
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Number of 


Directory Unit of Units 
Data Set Data Set Type Blocks Storage Required 
SYSI.LINKLIB partitioned 1 cylinder! 1 
(OS/VS1 only) 
SYS1.LPALIB partitioned 1 cylinder! 1 
(OS/VS2 only) 
VSAPL.OBJLIB partitioned 20 3200-byte 143 

block 
VSAPL.CNVTLIB partitioned 1 cylinder! 1 
VSPC library VSAM — 1000-byte 500 
unit 


1 Storage requirements for load module data sets are for a 3330. 


Figure 6. Auxiliary Storage Requirements for VS APL under OS/VS (VSPC) 


Directory Unit of Units Required 


Library or Disk File Tracks Storage 2314/2319 3340 3330 
Relocatable library 1 cylinder 8 12 6 
Core-Image library 2 cylinder 3 4 2 
Deblocked object - tracks 100 80 57 
deck file 

VSPC library or 1000-bytes 500 500 500 
(VSAM) 


Figure 7. Auxiliary Storage Requirements for VS APL under DOS/VS (VSPC) 


Under CMS, a VS APL workspace is a CMS file with a block size of 800 
bytes. Figure 8 shows the capacity per cylinder of the direct access storage 
devices supported by CMS in terms of 800-byte blocks and several data sizes. 


15K 25K 50K 
Device Blocks Clear WS Data Data Data 


2314 150 25 en Pe 2.5 
3330 266 44.3 13.3 8.1 4.1 
3340 96 16 4.8 2:9 1.5 


Figure 8. Auxiliary Storage Capacity per Cylinder 
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MESSAGES 


Messages under CMS 


Messages under VSPC 


Error and diagnostic messages that are issued by the CMS executor of VS 
APL are printed at the user’s terminal. They are identified by a message 
number prefix of APL. They are documented in VS APL for CMS: 
Terminal User’s Guide. 


A VS APL user can also receive messages issued by CP or CMS. CP and 
CMS messages are identified by message number prefixes of DMK and DMS, 
respectively. They are documented in IBM Virtual Machine Facility/370: 
System Messages. 


The following error and diagnostic messages are issued by the VSPC executor 
of VS APL and are printed on the VSPC online log. The VS APL user 
receives the message SYSTEM ERROR nnn, where nnn is the online log 
message number. 


APLP001I PGM CHECK LOOP IN APL PROCESSOR. 


Explanation: During processing of a program check, a second program check 
occurred. 


System Action: Message APLPO11I, which shows the PSW and general 
registers at the time of the second program check, is issued. A dump is taken, 
and execution is terminated. 


User Action: Report the problem to the system programmer. 


APLP002I PGM CHECK IN EXECUTOR. 


Explanation: A program check occurred in the VS APL executor. 


System Action: Message APLPO11I, which shows the PSW and general 
registers at the time of the program check, is issued. A dump is taken, and 
execution is terminated. 


User Action: Report the problem to the system programmer. 


APLP003I_ EXECUTOR SAVE AREA BLOCK FULL. 


Explanation: The executor is designed so that routine calls are nested to a 
maximum depth of five. An attempt to call a sixth-level routine was made, 
and there is no sixth save area. 


System Action: A dump is taken, and execution is terminated. 


User Action: Report the problem to the system programmer. 


APLP004I_ INVALID ASSIST CHECK CONDITION CODE. 


Explanation: During initialization, when a test was made for the presence of 
the VS APL microcode assist, an unexpected condition code was returned. 


System Action: Execution continues without use of the VS APL microcode 
assist. 


User Action: Report the problem to the system programmer. 
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APLPO0O0SI UNEXPECTED SYSTEM ERROR CODE RECEIVED. 
RET: xxx, REAS: yyy, SYS: www, APL: zzzzz. 


Explanation: An unexpected error code was received from VSPC following a 
service request. xxx is the return code, yyy is the reason code, www is the 
VSPC request code, zzzzz is the VS APL service request code. 


System Action: A dump is taken. A clear workspace is loaded. Execution 
continues. 


User Action: Report the problem to the system programmer. 


APLP006I_ NO SYSTEM INDICATOR ON ASYNCH ENTRY. 


Explanation: VSPC invoked the VS APL processor for an asynchronous 
occurrence. No indicator was set to distinguish the cause. 


System Action: A dump is taken. Execution continues. 


User Action: Report the problem to the system programmer. 


APLP007I_ MULTIPLE UNEXPECTED ERROR CODES FROM 
SYSTEM. 


Explanation: Multiple unexpected error codes were received from VSPC 
following similar service requests. 


System Action: A dump is taken, and execution is terminated. 


User Action: Report the problem to the system programmer. 


APLPOO8I APL ASSIST INCOMPATIBLE WITH APL PROCESSOR. 


Explanation: During initialization, when a test was made for the presence of 
the VS APL microcode assist, it was discovered that the microcode assist is 
not at the same level as the VS APL processor. 


System Action: Execution continues without use of the VS APL microcode 
assist. 


User Action: Report the problem to the system programmer. 


APLP009I INSUFFICIENT STORAGE FOR MINIMUM WS. 


| Explanation: The default workspace size defined in the user’s profile is too 
small for VS APL operation. 


System Action: A dump is taken, and execution is terminated. 


User Action: Report the problem to the account administrator. 


APLP011I PSW: eee XXxxxxxx, REGS: 


Explanation: VS APL has been terminated because of a program check. This 
message shows the contents of the program check old PSW and the general 
registers. It is issued following messages APLPO001I or APLPOOZ2I. 


System Action: Abend processing continues. 


User Action: Include this information when reporting the problem to the 
system programmer. 
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APLP014I1_ UNEXPECTED ERROR IN APL INTERNAL AP. 


Explanation: An unexpected error code was received from VSPC following a 
service request in an internal auxiliary processor. The prior message, 
APLPOOSI, gives additional information about the error. 


System Action: A dump is taken, and execution is terminated. 


User Action: Report the problem to the system programmer. 


Conversion Program Messages 


The following error messages are issued by workspace conversion programs 
and appear on the conversion report. With the conversion programs that run 
under CMS, the messages are also printed at the terminal. When a workspace 
or library is in error, its identification either appears in the message or 
preceding the message in the conversion report. 


There are messages in addition to those listed below that appear on the 
conversion report. They are directed to the workspace owner and are 
documented in VS APL for CMS: Terminal User’s Guide and VS APL 
for VSPC: Terminal User’s Guide. 

HDR LABEL I/O ERROR. CONVERSION CANCELLED 


Explanation: An unrecoverable error occurred while an input header label 
was being read. 


System Action: Execution of the conversion program is terminated. 


User Action: Obtain another copy of the input tape from the source APL 
system. 


Issued by: APLCVCMS, APLCVOS, APLCVDOS. 


TRLR LABEL I/O ERROR. CONVERSION CANCELLED 


Explanation: An unrecoverable error occurred while an input trailer label was 
being read. 


System Action: Execution of the conversion program is terminated. 


User Action: If the error occurred on the last or only volume, none. 
Otherwise, run the conversion program again using the remaining volumes. 


Issued by: APLCVCMS, APLCVOS, APLCVDOS. 
SYSTEM ERROR WHILE CONVERTING WORKSPACE/DIRECTORY 


libnum name. WORKSPACE/DIRECTORY UNCONVERTED AND 
PRESUMED DAMAGED 


Explanation: A program check occurred, probably because of invalid 
information in a workspace or directory. 


System Action: The contents of the program check old PSW and general 
registers are printed. Execution of the conversion program continues with the 
next workspace. 


User Action: Obtain another copy of the rejected workspace or library from 
the source APL system. 


Issued by: APLCVCMS, APLCVRPQ, APLCVOS, APLCVDOS. 
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ERROR UNRECOVERABLE. CONVERSION ABORTED 
Explanation: Repeated system errors have occurred. 


System Action: A storage dump is printed. Execution of the conversion 
program is terminated. 


User Action: Obtain another copy of the input tape from the source APL 
system. 


Issued by: APLCVCMS, APLCVRPQ, APLCVOS, APLCVDOS. 


WORKSPACE REJECTED, NOT CONVERTED, DUE TO I/O ERROR 


Explanation: An unrecoverable error occurred while the workspace was being 
read. 


System Action: Execution of the conversion program continues with the next 
workspace. 


User Action: Obtain another copy of the rejected workspace from the source 
APL system. 


Issued by: APLCVCMS, APLCVRPQ, APLCVOS, APLCVDOS. 


WORKSPACE FULL 
Explanation: The workspace is too large to be converted. 


System Action: Execution of the conversion program continues with the next 
object in the workspace. 


User Action: Have the owner of the source workspace compress it or split it 
into two workspaces and obtain a dump of the modified workspace. 


Issued by: APLCVCMS, APLCVOS, APLCVDOS. 
“WRITE ERROR rn WHILE SAVING libnum name. CONVERSION 
CANCELLED 


Explanation: An error return from the FSWRITE macro occurred. nn is the 
return code (see JBM Virtual Machine Facility/370: Command Language 
Guide for General Users.) The probable cause of the error is a full A-disk 
(return code 13). . 


System Action: Execution of the conversion program is terminated. 


User Action: Determine the reason for the error and correct it. Then run the 
conversion program again, specifying the RESUME option and the 
identification of the rejected workspace. 


Issued by: APLCVCMS. 


filename filetype IMPORT FILE SEQUENCE NUMBER nann 


Explanation: Display of the file sequence number nnnn of the converted 
workspace filename filetype on the output tape. 


System Action: None. 


User Action: Use the information when preparing VSPC Service Program 
control statements. 


Issued by: APLCVRPQ. 
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NOT A CMS DUMP TAPE. CONVERSION CANCELLED 
Explanation: The input tape is not a CMS dump tape. 

System Action: Execution of the conversion program is terminated. 
User Action: Mount the correct tape. | 


Issued by: APLCVRPQ. 


filename filetype filemode NOT AN APL/CMS (PRPQ) WORKSPACE. 
Explanation: The file is not an APL/CMS workspace. 


System Action: Execution of the conversion program continues with the next 
file. 


User Action: None, unless all files on the tape are so rejected. In this case, 
mount the correct tape. 


Issued by: APLCVRPQ. 

INADEQUATE SPACE TO RUN CONVERSION. CONVERSION 
CANCELLED | 

Explanation: There is less than 64K of free virtual storage space available. 
System Action: Execution of the conversion program is terminated. 

User Action: Define a larger virtual machine. 

Issued by: APLCVRPQ. 

filename filetype WORKSPACE TOO LARGE FOR VIRTUAL MACHINE 


SIZE. RERUN WITH LARGER MACHINE. WSSIZE IS xxxx NEED 
ABOUT yyyy BYTES TO CONVERT. 


Explanation: The workspace is too large to be converted. 


System Action: Execution of the conversion program continues with the next 
workspace. 


User Action: Define a larger virtual machine and run the conversion program 
again. 


Issued by: APLCVRPQ. 
filename filetype WORKSPACE DAMAGED OR INVALID. NOT 
CONVERTED. 


Explanation: Either internal pointers in the workspace are invalid, or the 
workspace is not Version 2. 


System Action: Execution of the conversion program continues with the next 
workspace. 


User Action: Obtain a valid copy of the rejected workspace from the source 
APL system. 


Issued by: APLCVRPQ. 
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WSID INVALID FOR VSPC. WORKSPACE (OR LIBRARY) REJECTED 


Explanation: The workspace name contains deltas or underscored characters 
or the library number exceeds seven digits. . 


System Action: Execution of the conversion program continues with the next 
workspace. 


User Action: Run the conversion program again, using a SELECT statement 
to provide a valid identification for the rejected workspace or library. 


Issued by: APLCVOS, APLCVDOS. 
* THIS LIBRARY DEFINED WITH DEFAULTS DUE TO SYSTEM 
ERROR 


Explanation: An error occurred while the directory for the library was being 
read. 


System Action: A user profile record containing default values for SPACE 
and SSMAX is written (see ‘User Profiles Created by Conversion Program’’). 
Execution of the conversion program continues. 


User Action: If defaults are acceptable, none. Otherwise, use the VSPC 
command ALTER to modify the user’s profile. 


Issued by: APLCVOS, APLCVDOS. 


SELECTION LIST FULL. COMMAND IGNORED 


Explanation: More than 100 SELECT statements were input to the 
conversion program. 


System Action: The SELECT statements in excess of 100 are ignored. 


User Action: Run the conversion program with the rejected SELECT 
statements. 


Issued by: APLCVOS, APLCVDOS. 


INVALID SELECT PARAMETER. COMMAND IGNORED 
Explanation: The SELECT statement contains an invalid parameter. 
System Action: The invalid statement is ignored. 


User Action: Correct the SELECT statement and run the conversion 
program again. 


Issued by: APLCVOS, APLCVDOS. 


INVALID DESCRIBE COMMAND. CONVERSION CANCELLED 
Explanation: The DESCRIBE statement contains an invalid parameter. 
System Action: Execution of the conversion program is terminated. 


User Action: Correct the DESCRIBE statement and run the conversion 
program again. 


Issued by: APLCVOS, APLCVDOS. 
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INVALID CONVERSION OPTIONS. CONVERSION CANCELLED 


Explanation: Either the RESUME statement contains an invalid parameter or 
a conversion control statement is unrecognizable. 


System Action: Execution of the conversion program is terminated. 


User Action: Correct the invalid statement and run the conversion program 
again. 


Issued by: APLCVOS, APLCVDOS. 
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APPENDIX A. VS APL COMPONENTS 


Listed below are the items that 
are contained in each component 
of VS APL. When you install VS 
APL, check the printed output of 
the installation procedure against 
these lists to verify that each 
component is complete. 


Interpreter Modules 


APLCOIBM 
APLIACHK 
APLIACIR 
APLIADEC 
APLIADOM 
APLIAENC 
APLIAFOR 
APLIAGFM 
APLIAGOU 
APLIAGRD 
APLIANAM 
APLIAPRD 
APLIAQFN 
APLIARED 
APLIAROT 
APLIASCN 
APLIASHF 
APLIASHV 
APLIASYV 
APLIATAK 
APLIATBC 
APLIATRN 
APLIATRS 
APLIATSP 
APLIECMX 
APLIEFCH 
APLIEFNM 
APLIEIDX 
APLIEMND 
APLIEPSI 
APLIEREV 
APLIERHO 
APLIESCA 
APLIESPA 
APLIETAK 
APLIEXAR 
APLIEXFR 
APLITCMC 
APLITCMD 
APLITCME 
APLITCMF 
APLITCMG 
APLITCMI 


APLITCML 
APLITCMS 
APLITCMT 
APLITCPI 
APLITCPO 
APLITERR 
APLITEX 
APLITFCH 
APLITFDC 
APLITFDE 
APLITFDN 
APLITFDO 
APLITFUN 
APLITHDR 
APLITIDS 
APLITIHI © 
APLITINI 
APLITINP 
APLITLXS 
APLITMSG 
APLITNCV 
APLITPRL 
APLITSUB 
APLITUSG 


CMS Executor Modules 


APLSCDPY 
APLSCERR 
APLSCFXI 
APLSCINI 
APLSCLIB 
APLSCMSC 
APLSCMSG 
APLSCOPY 
APLSCSHV 
APLSCSVI 
APLSCTBL 
APLSCTYP 


VSPC Executor Modules 


APLPAPAB 
APLPAPCD 
APLPCOAP 
APLPCOEX 
APLPCTBL 
APLPFXIM 
APLPLIBS 
APLPMISC 
APLPSERR 
APLPSHVR 
APLPTYIO 


Shared Storage Manager Modules 


(CMS only) 
ASUSHACC 


' ASUSHBPB 


ASUSHBVB 
ASUSHCPY 
ASUSHGET 
ASUSHOFR 
ASUSHPUT 
ASUSHQUE 
ASUSHREF 
ASUSHRET 
ASUSHSOF 
ASUSHSON 
ASUSHSPC 
ASUSHSRD 
ASUSHSUB 


Auxiliary Processors (CMS only) 


APL100 
APL101 
APL110 
APLI11 
APL123 


Auxiliary Processor Macros 


(CMS only) 


APLZCODE 
ASUPCV 
ASUSCV 
ASUSHSVP 
ASVPACC 
ASVPCPY 
ASVPOFR 
ASVPQRY 
ASVPREF 
ASVPRET 


‘ ASVPSOF 


ASVPSON 
ASVPSPC 
ASVPWAIT 


CMS Conversion Modules (for 
APLCVCMS) 


APLCCULL 
APLCDISP 
APLCFUNC 
APLCGRUP 
APLCIBNM 
APLCINIT 
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APLCLEAR 
APLCMISC 
APLCOIBM 
APLCPARM 
APLCRPRT 
APLCSAVE 
APLCSHIP 
APLCSPIE 
APLCTBCD 
APLCVARB 
APLCWKSP 
APLCWSFN 
APLIESPA 
APLIEREV 
APLITFDC 
APLITHDR 
APLITIDS 
APLITLXS 
APLITNCV 


CMS Conversion Modules (for 
APLCVRPQ) 


APLCOIBM 
APLCSHIP 
APLCTBCD 
APLIESPA 
APLITFDC 
APLITHDR 
APLITIDS 
APLITLXS 
APLITNCV 
APLQDISP 
APLQFUNC 
APLQGRUP 
APLQIBNM 
APLOQINIT 
APLQLEAR 
APLQMISC 
APLQPARM 
APLQRPRT 
APLQSAVE 
APLOSPIE 
APLQVARB 
APLQWKSP 


VSPC/OS Conversion Modules 


APLCOIBM 
APLIEREV 
APLIESPA 
APLITFDC 
APLITHDR 
APLITIDS 
APLITLXS 

. APLITNCV 
APLOCULL 
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APLODIRE 
APLODISP 
APLOFUNC 
APLOGRUP 
APLOIBNM 
APLOINIT 
APLOLEAR 
APLOMISC 
APLOPARM 
APLORPRT 
APLOSAVE 
APLOSHIP 
APLOSLST 
APLOSPIE 
APLOTBCD 
APLOTIDY 
APLOVARB 
APLOWKSP 
APLOWSFN 


VSPC/DOS Conversion Modules | 


APLCOIBM 
APLDCULL 
APLDDIRE 
APLDDISP 
APLDFUNC 
APLDGRUP 
APLDIBNM 
APLDINIT 
APLDLEAR 
APLDMISC 
APLDPARM 
APLDRPRT 
APLDSAVE 
APLDSHIP 
APLDSLST 
APLDSPIE 
APLDTBCD 
APLDTIDY 
APLDVARB 
APLDWKSP 
APLDWSFN 
APLIEREV 
APLIESPA 
APLITFDC 
APLITHDR 
APLITIDS 
APLITLXS 
APLITNCV 


APPENDIX B. SAMPLE TERMINAL SESSION FOR 
VS APL UNDER CMS 


Log on to VM/370, IPL CMS, and execute the VS APL session shown 
below. You must have access to the disk on which the VS APL system resides 
and to the Y-disk on which the distributed workspaces reside. 


APL APL100 Invoke VS APL and the 
auxiliary processor that 
issues CP and CMS commands 


VS APTI 
CLEAR WS 
100 OSVO 'xXx! Establish connection with 
2 auxiliary processor 
X*«'ZL * WO000001 Y' Issue CMS command to list 
NEWS WOOO0O0O0O01 Y1 workspaces in public library 1 


TYPEDRIL W0000001 /Y1 
APLCOURS W0000001 /Y1 
CONVERT W0000001 Y1 
EXAMPLES Wo000001 /Y1 


PLOT WOO000001 Y1 
FORMAT WOOOO0O001 Y1 
WSFNS WOO0O0O0001 Y1 
SEDIT WOO0OO00OO0O1 Y1 
MEDIT WOO0O00OO0OO0O1 /Y1 
HOWEDITS W0O000001 Y14 
SBIC -wooo0ooceodo1 Y¥1 
)LOAD 1 EXAMPLES Load workspace 
SAVED 08:50:42 06/12/75 
FINDTYPE '7' Data type of argument is ... 
1 character 
FINDTYPE 7 : Data type of argument is ... 
0 numeric 
JOFF HOLD Log off VS APL and return 
el to CMS 
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APPENDIX C. SAMPLE TERMINAL SESSION FOR 
VS APL UNDER VSPC 


Log on to VSPC and execute the VS APL session shown below. If the user 
number that you log on with has a content attribute of APL, omit the first 


statement. 

ENTER APL Invoke VS APL 
VS APL 

CLEAR WS 
)LOAD 2 VSFILES Load workspace 


SAVED 11:05:17 07/29/75 
'S' ACREATE '‘SAMPLE' Create VSPC APL file to 
be accessed sequentially 


AWRITE 3 49112 Open file and write record 1 
AWRITE 4 39112 Write record 2 
AREAD Read record 1 
14 2 3 4 
5 6 7 8 
9 10 11 12 
AREAD Read record 2 
dc 2. 33 
4u 5 6 
7 #8 9 
10 11 12 
AREAD There is no record 3; 
file is closed 
DROP ‘SAMPLE! Purge the file 
)OFF HOLD Log off VS APL and return 
peaLlt to VSPC 
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GLOSSARY 


The following terms are defined as they are used in this 
publication. If you do not find the term you are looking for, 
refer to the index or tothe JBM Data Processing Glossary, 
GC20-1699. 


A-disk: In CMS, a user’s primary disk; accessed in read/write 
mode when a CMS terminal session is begun. 


account administrator: A VSPC user who has limited authority 
to use the VSPC Service Program and to define and alter user 
profiles. 


auxiliary processor: A program that communicates with other 


programs via shared variables. 


chief administrator: A VSPC user who has full authority to use 
the VSPC Service Program and to define and alter user, 
foreground processor, and auxiliary processor profiles. 


content attribute: In VSPC, information associated with a 
workspace that identifies its foreground processor or 
indicates its contents. 


content conversion: A form of workspace conversion in which 
the contents of a workspace are analyzed and modified; 
includes format conversion. 


conversion program: The component of VS APL that converts 
APL \ 360, APLSV, and APL/CMS workspaces to VS APL 
workspaces. 


core image library: A DOS/VS library used to store link-edited 
programs. For DOS/VS(VSPC), the core image library is 
used to contain the APL foreground processor and the APL 
workspace conversion program. 


executor: The component of VS APL that provides 
environment-dependent services for the interpreter. 


filemode: In CMS, the third field of a file identifier; identifies 
the virtual disk on which the file resides and the mode in 
which the disk can be accessed. 


filename: In CMS, the first field of a file identifier. 


filetype: In CMS, the second field of a file identifier; may 
implicitly define certain file characteristics. 


foreground processor: A processor, such as VS APL, that 
operates under the control of VSPC. 


format conversion: A form of workspace conversion in which 
only the format of a workspace is modified. 


full conversion: A form of workspace conversion in which all 
input workspaces are converted. 


internal auxiliary processor: An auxiliary processor that is part 
of the VS APL (VSPC) executor, rather than a separate 
program. 


interpreter: The component of VS APL that scans, analyzes, 
and executes VS APL statements. 


library manager: A VSPC user whose user number is that of a 
public or project library. 


library table file: A file that defines public and project 
libraries to VS APL under CMS. 


private library: A library that is normally available only to a 
single user. 


profile: A collection of information about a user, a 
foreground processor, or an auxiliary processor. 


project library: A library that is normally available to a set of 
users. 


public library: A library that is normally available to all users. 


relocatable library: A DOS/VS library containing relocatable 
object modules. For DOS/VS(VSPC), the relocatable library 
is used to contain object decks from the VS APL distribution 
volume. 


selective conversion: A form of workspace conversion in 
which only specified input workspaces are converted. 


service program: In VSPC, a program that is used to manage 
the VSPC library and to define and alter profiles. 


shared storage manager: The component of VSPC or of VS 
APL under CMS that manages the communication between 
auxiliary processors. 


system disk: In CMS, the disk that contains the CMS nucleus 
and disk-resident command modules; accessed in read/only 
mode when a CMS terminal session is begun. 


workspace: An area of virtual storage assigned to a user for 
his exclusive use. Also, the contents of that area when stored 
as a file. 


Y-disk: In CMS, a disk that is an extension of the system disk. 


- It contains VS APL modules, procedures, and public libraries. 
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INDEX 


A 


A-disk,CMS 
for installing VS APL 20-22 
for VS APLuser 39 
for workspace conversion 50 
list of files 21 
space required for VS APL 70 
AUTH statement, VSPC 
for installing VS APL 
under DOS/VS (VSPC) 31,36-37 
under OS/VS (VSPC) 30,25 
for transferring converted 
workspaces 55 
auxiliary processor macros 
description 13 
list of names 81 
auxiliary processors 
description 13 
how to define 
toCMS 41 
to VSPC 41,29-30 
identification 
for CMS 41,22 
for VSPC 41 
auxiliary storage required by conversion programs 50 
auxiliary storage requirements 69-71 
auxiliary storage requirements for workspaces 70 


C 


changing workspace identifications 
after conversion 53-55 
before conversion 49 
during conversion 
under CMS 53 
under VSPC 57 
required changes 49,51,55 
components of VS APL 
description 13 
list of contents 81-82 
content conversion 
description 50 
how to specify 
for CMS 52 
for VSPC 56 
conversion (see workspace conversion) 
creating VS APL libraries 
under CMS 43-46 
under VSPC 46-47,29-30 


D 


DEFINE statement, VSPC 
for auxiliary processors 30 
for converted libraries 60-61 
for project libraries 46 
for public libraries 46,30 
for VS APL 30 
for VS APL user 40 


defining auxiliary processors 
toCMS 41 
to VSPC 41,30 
defining VS APL libraries 
toCMS 43-46 
to VSPC 46-47,29 
defining VS APL users 
to VM/370 39 
to VSPC 40 
DESCRIBE statement, conversion program 57-58 
directory entry, VM/370 
for project library disk 46 
for VS APL user 39 
distributed workspaces 
auxiliary storage requirements 70 
description 13 
how to transfer to VSPC 29-30 
identification 16,17 
distribution volume, VS APL 16,17 
DOS/VS workspace conversion program 60 


E 


error messages 
conversion program 75-79 
under CMS 73 
under VSPC 73-75 
executor, VS APL 
description 13 
list of modules 81 
messages 73-75 
EXPORT statement, VSPC 64 


F 


format conversion 
description 50 
how to specify 
for CMS 52 
for VSPC 56 
format of conversion program statements 56 
format of VS APL distribution volume 15 
FORMAT statement, conversion program 56 — 
full conversion 
description 49 
how to specify 
for CMS 52 
for VSPC 57 


G 


G-disk,CMS 
for project libraries 45 
how to define 46 
restriction on definition 39,46 


H 


how to maintain a public library 44-45 
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I Pp 


IMPORT statement, VSPC passwords 
for converted workspaces 55 for project library disks 46 
for distributed workspaces 30 for VSPC, restrictions 49 
for workspaces transported from CMS 63 private library 
installing VS APL under CMS 39 
under DOS/VS (VSPC) 31-38 under VSPC 40 
under OS/VS (VSPC) 25-30 profile, VSPC user 
under VM/370 (CMS) 19-23 created by conversion program 60-61 
internal auxiliary processors example 40 
description 13 project library 
how to define to VSPC 29-30 under CMS 
identification 41 description 45 
interpreter, VS APL how tocreate 45-46 
description 13 how to maintain 46 
list of modules 81 under VSPC 
: how tocreate 47 
J how to maintain 47 
public library 
JCL for DOS/VS under CMS 


how to punch 32 

to build core image library 34 
to build relocatable library 33 
to define private libraries 32 


description 44 

how to add or replace a workspace 44 
how tocreate 44 

how to delete a workspace 45 


to run conversion program 60 under VSPC 

to run VSPC Service Program 35-37 how to create 46 
JCL for OS/VS how to maintain 47 

how to punch 26 

to build VS APL object module library 27 Q 

to define OS libraries 27 

to link-edit conversion program 28 quotas, VSPC 

to link-edit VS APL load module 28 library space 58 

to run conversion program 59 number of shared variables 61 

to run VSPC Service Program 29-30 shared variable size 58 
L R 
library (see private library, project library, public library) RESUME statement, conversion program 57 
library number, restriction 49 resuming workspace conversion 
library space quota 58 description 49 
library table file 43 under CMS 52-53 
link-edit under VSPC 57 

conversion program 28 

VS APL load module 28 S 
M sample JCL (see JCL) 

sample terminal session 

macros, auxiliary processor for CMS 83 

description 13 for VSPC 85 

list of names 81 SELECT statement, conversion program 57 
maintaining VS APL libraries “ selective conversion 

under CMS 44-46 description 49 

under VSPC 47 how to specify 
messages for CMS 52 

conversion program 75-79 for VSPC 57 

under CMS 73 shared storage manager 

under VSPC 73-75 description 13 
microcode assist 67 list of modules 81 

shared system 

O installing 19-23 


storage requirements 
auxiliary 69-71 
virtual 69 
virtual machine size 39 
shared variable quotas 58,61 


OS/VS workspace conversion program 59 
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storage requirements 
auxiliary storage 
for VS APL 69-71 
for workspace conversion 50 
for workspaces 70 
virtual storage 69 
syntax conventions 4 
system disk, CMS 23 


T 


terminal session, sample 

for CMS 83 

for VSPC 85 
transferring conversion program output to VSPC 61 
transporting workspaces 

from CMS to VSPC 63 

from VSPC to CMS 64 


U 


user profile, VSPC 
created by conversion program 60-61 
example 40 
users of VS APL 
how to define to VM/370 39 
how to define to VSPC 40 


Vv 


virtual storage requirements 69 
VM/370 directory entry 
for project library disk 46 
for VS APL user 39 


Ww 


workspace conversion 
error messages 75-79 
input 
description 49 
restrictions 49 
options 49-50 
output 
general description 50 
under CMS_ 50,55 
under VSPC 60 
under CMS 
auxiliary storage requirements 50 
procedure 51-55 
program names 50 
under VSPC 
control statements 
description of format 56 
DESCRIBE 57-58 
FORMAT 56° 
RESUME 57 
SELECT 57 
procedure 56-58 
program names 56 
sample JCL for DOS/VS_ 60 
sample JCL for OS/VS 59 
user profiles 60-61 
workspace conversion under CMS 50-55 
workspace conversion under VSPC 56-61 


workspace identification 
APL/CMS workspaces 51 
converted workspaces 
forCMS 51 
for VSPC 61 
how to change 
after conversion 53-54 
before conversion 49 
during conversion 
under CMS 54 
under VSPC 57 
restrictions 49 
under CMS 
private workspaces 51 
project workspaces 45 
public workspaces 44 
workspace size 
computed by conversion program 60 
how to compute 70 
minimum 69 
restrictions for VSPC 40,47 
workspaces, distributed 
auxiliary storage requirements 70 
‘description 13 
how to transfer to VSPC 29-30 
identification 16,17 


Y 


Y-disk, CMS 
for installing VS APL 19-23 
for public libraries 44 
for VS APL user 39 
list of files 21 
space required for VS APL 70 
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